What is your best practice for your changelog when maintain 2 versions for 1 code base?

[longtth]

As title, for some reason, I'm maintaining 2 version for 1 code base at the same time, and it will take a long time before it can be merged to 1 branch.

Currently, I'm maintain it in 2 master branches (master and master-2)

So, have you ever faced the same problem like me, what did you do for maintain changelog for that?
If you would have to, what will you do?

Any other best practice to maintain this kind of application is appreciated 🥰🥰🥰

[axd1967]

Looks like the 1.y branch is a kind of support branch?

[longtth]

Looks like the 1.y branch is a kind of support branch?

Do you mean that I should save all change log in a 1.y branch?

English is not my mother language, which keyword should be used to search about these practices?

[axd1967]

IMHO all branches (i.e v1 AND v2) should update their changelog.

if a branch is merged, then changelogs are merged too. (by the way, this also applies for feature branches.)

but why do you keep two branches?

[Natureshadow]

I was just about to ask a very related question.

A reason for keeping a second branch is in fact a support branch.

We have the following situation:

• Release 2.4
• Release 2.5
• Release 2.6

At this point, we realised that 2.4 and 2.5 had a serious bug. What do we do now? There are three options:

1. Yank the two releases
2. Release 2.4.1 and 2.5.1, backporting the fix
3. Ignore the problem and accept that there are two broken minor releases out there

for option 2, where does the changelog go? The changelog entry about the fix already goes into 2.6.1, because this is the newest version (on master) where the problem is fixed. Now when we backport the fix, what do we do?

• Add a 2.4.1 and 2.5.1 changelog to the 2.4 and 2.5 branches, and to the releases? Of course yes
• But: Do we merge these releases into the master / 2.6.1 changelog? Or do we keep the bugfix releases 2.4.1 and 2.5.1 out of the 2.6.1 / master changelog?

[longtth]

@Natureshadow

But: Do we merge these releases into the master / 2.6.1 changelog? Or do we keep the bugfix releases 2.4.1 and 2.5.1 out of the 2.6.1 / master changelog?

not the best practice but in my project, I'm just leave the changelog for branch 2.4 and branch 2.5 only

if you fix the bug in branch 2.6, then it has the changelog line ver 2.6.1 for the bug it self.
incase you don't need to fix the bug in branch 2.6, then the actual code doesn't exist here -> don't need to describe it.

[axd1967]

Depends on whether those older versions are still used (eg using new versions requires a new payment from the user... is the user somehow "stuck" to a release ...).

The intention is that the users of all those versions are aware of the change/correction. Therefore each changelog should refer to those changes.

One - IMHO clean - option is to correct the bug in 2.4 (giving 2.4.1) and merge to 2.5.1 and 2.6.1 (assuming it has been released) and master.
This will require a merge of the changelogs too, and probably some conflict solving in the changelog. As far a I can see this is often the cleanest way to deal with a bug that appears in older versions.

(To me it sounds logical that merging branches also always means merging changelogs.)

It is also possible that the bug was discovered and solved in 2.6 and later found that it also exists in 2.4-2.5. Then it will not be possible to merge "back" to 2.4./2.5. The bug is to be solved again in 2.4 and merged to 2.5 (again: this always depends on whether this is desired by 2.4/2.5 users), in which case the 2.5.1 changelog will contain the merged changes from 2.4.1, which is what we want.

So IMHO the first question is to wonder (1) where did the bug appear, and (2) which version should benefit from a bug correction; then, merge to successive versions; and be aware that more recent versions might pose more merge problems. Or solve the bug in the various maintenance branches, which is probably more work intensive.

But whatever scenario is followed, in the end all changelogs will somehow refer to that bug.

(To be discussed: also indicate in 2.4.1 and 2.5.1 - the older versions - that the changes have also been incorporated in future versions 2.5.1 and 2.6.1?)

(Not sure what is being meant by "yanking a release", can this be clarified? If a release can simply be deleted, then there is no issue, but it is a bad practice.)

(Another interesting issue to be aware of is the appearance of a bug in a maintenance branch... But that's too off-topic now.)

[Natureshadow]

One - IMHO clean - option is to correct the bug in 2.4 (giving 2.4.1) and merge to 2.5.1 and 2.6.1 (assuming it has been released) and master. This will require a merge of the changelogs too, and probably some conflict solving in the changelog. As far a I can see this is often the cleanest way to deal with a bug that appears in older versions.

But then the changelog will list buggy releases in between fixed releases: 2.4 - buggy 2.4.1 - fixed 2.5 - buggy 2.5.1 - fixed 2.6 - buggy 2.6.1 - fixed

[axd1967]

if that happens, then that's where the change log needs to be dealt with as part of the merging process.

but normally the change log of the bugfix branch will contain a line with the change but without the version. example:

current <<<--- this section is where developers add high level change information. it is removed/changed/merged by the release manager

- solve bug X

2021-12-03 : v 2.4
- did this
- changed that
- etc

remember that during the solving of the bug, you don't know yet in what version the change will end up; that's the decision of the merge manager, who will add the version info at the top of the change log. it's not up to the developer of the bug/feature branch to add version info, only what changed.

then, each version will receive the changes that were applied in the bugfix branch; for each released version, it is the release manager that will decide on the final content of the changelog.

reviewing/amending the change log is part of the release process; that includes deciding on the version number (which then ends up in the changelog).

[CodeMyGame1]

(Not sure what is being meant by "yanking a release", can this be clarified? If a release can simply be deleted, then there is no issue, but it is a bad practice.)

According to the Keep a Changelog FAQ - "What about yanked releases?", yanked releases are those that "had to be pulled because of a serious bug or security issue", i.e. it's so dangerous that you wouldn't want people upgrading to that version at all. Hope this helps clarify the term @axd1967.