Add Changelog to document project changes

[wmontwe]

We want to introduce a changelog for Thunderbird for Android and K-9 Mail. It will serve as a base for creating the project’s release notes and document user facing version changes.

We will follow the specification provided by Keep a Changelog, which is widely used to document project changes. The specification provides a standardized format for maintaining changelogs.

Current state (2024-06-18):

We use the existing xml based changelog and update it reqularly until we have a ticks all the boxes version. This means:

• Link the existing XML in the readme: Add changelog link to readme #7975
• Update the XML changelog whenever there is a user facing change
• Enforce update via CI

[cketti]

Adding a bit more context.

Places where we currently publish a list of changes:

• In-app changelog
• App stores (Google Play has a character limit lower than the typical size of our complete list of changes)
• GitHub release page, e.g. https://github.com/thunderbird/thunderbird-android/releases/tag/6.804
• Published on the web, e.g. https://thunderbird.github.io/thunderbird-android/changelog_6.8-MAINT_branch.xml

We currently maintain an XML-based changelog that is used for the in-app changelog and is published on the web. Theoretically it supports translations. But in practice it's not happening because of missing tooling support.

During a release we manually create a text file containing the list of changes for F-Droid (see app-metadata/…/changelogs/). We currently ignore character limits. These files can be translated via Weblate. However, we currently don't hold a release until the release notes are translated.

The text file is used as a base for the release notes on Google Play. If necessary the list is manually trimmed down until it satisfies Google Play's character limit.

Things we've talked about, but haven't decided on (as far as I remember):

• Publish release notes on thunderbird.net, similar to how Thunderbird for desktop does it, e.g. https://www.thunderbird.net/en-US/thunderbird/115.0/releasenotes/
• Stop shipping the changelog contents inside the app (either link to the version published on the web or display it inside the app using a WebView)
• Allow contributors to translate the changelog published on the web/inside the app

Ideally, we only want to maintain one changelog and generate the others from that single source. Since there's a character limit on the app store release notes and we don't want to limit ourselves to that, we need a way to flag important entries so tooling can extract only those entries when generating the app store release notes. That tooling would also need to make sure all flagged entries combined don't exceed Google Play's character limit.

[wmontwe]

While your right that we need to solve all this questions, this issue aims to reduce workload during release preparation. It will allow us to shift the creation of a changelog from the release preparation to earlier in the development cycle, by updating it on a regular basis.

It will be the base to generate all the different variations with their own limitations and requirements in a separate step.

[cketti]

If the only goal right now is to incrementally build up the changelog during the development cycle, we can use the existing XML file.

Example:

<?xml version="1.0" encoding="utf-8"?>
<!-- … -->
<changelog>
    <release version="next" versioncode="39002" date="unreleased">
        <change>Fixed a bug</change>
    </release>

    <release version="6.901" versioncode="39001" date="2024-05-15">
        <change>Fixed a crash when opening the screen to compose a message</change>
    </release>
    <!-- … -->
</changelog>

Without having a clear idea of what we want to support eventually, it's hard to tell if "Keep a Changelog" is a suitable file format. Introducing it now only as a source to manually copy from during the release process doesn't feel like an improvement. We can have the "update changelog during development" feature without it.

[wmontwe]

I'm confused as we talked about this and we decided to move on with this approach. Please raise your concerns early on during the planing session.

[cketti]

Open questions that I think need to be answered before selecting a file format:

• How do we mark entries that should go into the app store release notes so those can be automatically extracted from the change log?
• Do we want to support translations (Thunderbird currently doesn't translate release notes)? If so, which translation platform are we using (Weblate or Pontoon)? That choice limits what file formats we can use. Do we chose one of the supported file formats or add extra tooling to create separate file(s) from a changelog with a file format of our choosing?
• What are the constraints for publishing release notes on thunderbird.net? Does our file format of choice support these constraints? Should we use whatever file format Thunderbird is using?

It's fine if we want to defer answering these questions until later. But we shouldn't introduce a new file format if we don't have the answers.

Building up the changelog incrementally doesn't require answers to all these questions. We can use the existing XML file now and still switch to a different format once we have the answers.