Addon Changelog

[QuackieMackie]

I haven't seen this yet, but I'd love to see an option for developers to be able to write change logs.
As the only current way I can see users can see whats changed is by checking the site it's downloaded from.

So when for example I update addon Demo/Test from version 1.0.2 -> 1.0.3 it would appear when I hit the upgrade button in the admin control panel.
It would bring up a value from the json.

An example could be:

{
    "legacy_addon_id": "",
    "title": "Demo - Test",
    "description": "This is a test addon.",
    "version_id": 1000030,
    "version_string": "1.0.3",
    "dev": "QuackieMackie",
    "dev_url": "",
    "faq_url": "",
    "support_url": "",
    "extra_urls": [],
    "require": [],
    "icon": "fa-user",
    "changelog": {
        "1000030": [
            "Fixed bug where databse table wasn't being created.",
            "Added new options:<ul><li>By category</li><li>By date</li></ul>",
            "Changed icon from <b>fa-cog</b> -> <b>fa-user</b>"
        ],
        "1000020": [
            "Minor tweaks in wording."
        ],
        "1000010": [
            "Initial release of the test addon."
        ]
    }
}

 

[Kirby]

I like the idea of providing a standardized way to present things like changelog, license and manual / readme to the end user.

But I don't think embedding such documentation keyed by version ID in addon.json is a good idea:

1. Versions IDs don't mean anything to users and not every Add-on (including your example, your version ID is 1.0.0 Beta 0) uses the recommended version ID format so it might not be possible to infer a meaningful version string from the version id
2. Keeping (possibly large amounts of) text in addon.json IMHO needlessly increases its size which might be kinda inefficient
3. Writing such documentation in JSON feels awkward and complicated

I'd rather like to see smth. similar to the various URLs, maybe smth. like

"files": {
    "Changelog": "CHANGELOG.md",
    "License": "LICENSE",
    "Readme": "README.md"
}

with Markdown, Plaintext and HTML being allowed (format determined by extension), especially as some Add-ons might already have such files anyway.

 

[QuackieMackie]

oVersions IDs don't mean anything to users and not every Add-on uses the recommended version ID format so it might not be possible to infer a meaningful version string from the version id

Thats fair, I didn't think about those who don't use the recommeneded version id's.

Writing such documentation in JSON feels awkward and complicated

I took insperation from a project I worked on previously, where we used toml files instead of json.
How we added the change log was like this:

changelog = """
Our change log goes here...
"""

How would the .md format work, would it just be an openable link added to the addon management area?
Would we be able to view each update individually?

---

The idea to use md instead of the json is great, but I feel like it could use some refining.

Instead of a single md file, could we get a changelog folder? When we bump a addons version, it would create a new md file in that folder attached to the version name.
The command to bump the version could also be expanded to have a toggle option if the author wants no change log to exist for that version.
Each version bump would add a new change log to the addon, these would be stored in the json.

So for example my addon has 3 versions

{
    "legacy_addon_id": "",
    "title": "Demo - Test",
    "description": "This is a test addon.",
    "version_id": 1000030,
    "version_string": "1.0.3",
    "dev": "QuackieMackie",
    "dev_url": "",
    "faq_url": "",
    "support_url": "",
    "extra_urls": [],
    "require": [],
    "icon": "fa-user",
    "changelog": {
        "1000030": "changelog_1000030.md",
        "1000020": "changelog_1000020.md",
        "1000010": "changelog_1000010.md"
    }
}

These change logs would be generated and stored in a folder called changelog/
If we wanted to go one step further, we could also add an overide command for the json, so if it's like this when the folder the changelogs are stored in are overriden by the folder name

    "changelog": {
        "override": "new_changelog_folder",
        "1000030": "changelog_1000030.md",
        "1000020": "changelog_1000020.md",
        "1000010": "changelog_1000010.md"
    }

 

[Kirby]

Thats fair, I didn't think about those who don't use the recommeneded version id's.

Well, you don't even use the recommended format in your example

How would the .md format work, would it just be an openable link added to the addon management area?

XenForo already has (some) support to render Markdown as HTML, so it should be relatively easy to add support to display such content in ACP.

Would we be able to view each update individually?

Probably not. But to be honest I don't know many (open source) projects that have individual changelogs.
Do you have examples for such projects?

Instead of a single md file, could we get a changelog folder? When we bump a addons version, it would create a new md file in that folder attached to the version name.

Might be possible. Though personally I prefer to have everything in just one CHANGELOG.md, especially as there are already tools to automate generating this (in combination with conventional commits and semantic versioning).

 

[QuackieMackie]

Well, you don't even use the recommended format in your example

Well thats stumped me I didn't even realise. Thanks for letting me know, i've got a few projects that have been doing it incorrectly.

Probably not. But to be honest I don't know many (open source) projects that have individual changelogs.
Do you have examples for such projects?

Thats just how I've always done it honestly. I prefer to split my changes into seperated areas.

Do you have examples for such projects?

https://github.com/kubernetes/kubernetes/tree/master/CHANGELOG
https://changelogs.ubuntu.com/