Changelog handling

This page describes our changelog handling among releases and branches. It's part of the way we set up release candidates and new (feature / bugfix / beta) releases.

goals

• handle changelogs for
  • current development (on branch master) resulting in so-called "nightlies",
  • preparing for a release candidate / beta version (on branch release),
  • publishing a beta version or a feature release (from branch release),
  • development and publishing of bugfix releases (built on top of a feature release, on branch release)
• straightforward documentation of relevant changes for nightlies and released versions
• hassle-free management on branching for a new release and on releasing a new version
• changes on release should be visible on master as well
• changes should be translatable, at least those coming from master (main development branch)
• changelog from master must not be renamed (or contents copied) on branching to release (as this will trigger retranslations, which we want to avoid)

involved files

file name	contents	updated on master	updated on release
res/raw/changelog_base.md	contains all changes until a feature release is published	x	x
res/raw/changelog_bugfix.md	contains all changes after a feature release	-	x
src/.../utils/BranchDetectionHelper.java	contains the version name for feature release	-	x

handling:

The following list is meant to be as checklists for different stages of development:

ongoing development on branch master

• changes are documented in changelog_base.md on master

branching to release

• branch master to release
• empty version code in BranchDetectionHelper.java on release
• empty changelog_bugfix.md on release, and insert a ## line only (for CrowdIn to recognize the change)
• empty changelog_base.md on master (every change in new release will be documented on release only - helps reducing merge conflicts)

further changes:

• document further changes on release in changelog_base.md on release
• regularly merge release back into master - changelog_base.md will be excluded from this
• document further changes on master in changelog_base.md on master

create a RC on release

• set version code in BranchDetectionHelper.java on release to 2023.xx.yy-RC (in variable FEATURE_VERSION_NAME)

further changes: (same as above)

feature release from release

• set version code in BranchDetectionHelper.java on release to 2022.xx.yy (in variable FEATURE_VERSION_NAME)
• merge release to master
• follow rest of regular release procedure

further changes:

• document further changes on release in changelog_bugfix.md on release
• regularly merge release back into master
• document further changes on master in changelog_base.md on master

bugfix release from release

• set version code in BranchDetectionHelper.java on release to 2022.xx.yy (in variable BUGFIX_VERSION_NAME)
• follow rest of regular release procedure

further changes:

• document further changes on release in changelog_bugfix.md on release (above the most recent version info), make sure to prepend a new line with ## when inserting the first entry after a bugfix release
• regularly merge release back into master
• document further changes on master in changelog_base.md on master

Notice: "Emptying a changelog" actually means "delete everything and insert a ## line after that" - this avoids a problem with Crowdin not updating/resetting translations for an empty changelog file.