Improve our Changelog management

[AurelienFT]

Discussion

Our team has grown since the last months and we want to be able to merge smaller PRs with a more faster pace. We previously had an issue with long CI times and flakiness (not fully resolved) that we deeply improved. We are currently facing a problem that make developers loose time and reduce our pace : merge conflicts on CHANGELOG.md.

The problem with these conflicts is that they dismiss existing reviews and this will make loose time and focus to multiple developers : the PR authors and the reviewers that need to come back to the PR verify why their review has been dismissed (no other changes than CHANGELOG.md) and re-approve. This can be seen has a small issue but when it affect 100 PR with 2 reviewers per week it's 200 re-approve and their associated time and focus shift that can be avoided.

To address this problem there is few things that we need to make sure we don't sacrify :

• Fast to write the changes for a PR.
• No need to be tight to conventional commits
• Follow the "KeepAChangelog" format that we already have
• Be able to add a entry in multiple category
• Be able to verify that the changelog entry for a specific PR has been added
• Easy to manipulate in case of release

Given all of this conditions and some internal rules that we also have I didn't found any solution that can fit our needs and so I designed a solution that I think that can be created and applied easily (not too much dev time (1 day)), don't change too much the developer habitude and can be automated through Github Actions.

I called this solution "Fragmented KeepAChangelog", nothing really revolutionary in CHANGELOG world but I think ""fractionize"" our CHANGELOG is the easiest way to solve all of our problems following our criterias. Now let's breakdown how this could work :

A new folder (with sub-folders) would to be created that would allow every PR to add one or multiple change entry depending on the type of the entry, it could look like :

|--unreleased
|----added
|------1637.md
|------.gitkeep
|----fixed
|------3389.md
|------.gitkeep
|----breaking
|------1637.md
|------.gitkeep
...

This format has a sub-folder for each category it prevent text convention in entry change if all the files were in the root which makes developers gain some time and facilitate automation. Each file is named by the PR number to simplify automation also and because they are in sub-folder by category they will not collide if we need an entry in "Added" and "Breaking" (like in the example).

Each file will contain a small text with the changes of his PR containing the same information as the existing format (a small side effect I anticipate is that people will write a bit more if it's one file per PR but I think it's a cool side effect). Example of a file named 1637.md :

New field in structure `Transaction` to give a color to the unicorns in the paradise

When we want to make a release we can have a GitHub Action that will scan this unreleased folder and extract all the information to build the section for this new version in the CHANGELOG.md. This action can be triggered either on a specific branch name, a label or a manual trigger this can be determined afterwards. The folder will look like this after :

|--unreleased
|----added
|------.gitkeep
|----fixed
|------.gitkeep
|----breaking
|------.gitkeep
...

And the CHANGELOG file :

[Version 0.0.1]

### Added
- [1637](https://github.com/FuelLabs/fuel-core/pulls/1637): New field in structure `Transaction` to give a color to the unicorns in the paradise.

Resolving this discussion

This proposition is open for comments until 15 february 2025. After this date if we didn't had any hard objections or alternative accepted I will develop this system.

Happy to your thoughts @FuelLabs/client

[netrome]

Nice, this sounds like a significant improvement to our workflow. I'm all for it! Thanks for the proposal 🚀

[rafal-ch]

Thanks for proposing this, I'm happy to try it 👍

[xgreenx]

I'm okay with the approach, but have several questions:

How do we want to enforce people to update changelog folder?=D Before we checked that CHANGELOG.md is modified, but now we need to check that folder is modified somehow.

How the bot that generates the final changelog looks like? Do we want to make a requirement during the realize to run it manually?

[AurelienFT]

@xgreenx
1 - Yes we will look if a file with the name == PR number exists.
2 - There is multiple solution, one is to tag a PR as release which will trigger a Github Action to commit the merge of all changelog on this PR.