Tooling: Can we come up with another way to edit `CHANGELOG` and `schema-next.yaml`?

[braydonk]

I apologize if this is already tracked somewhere.

If we have a long running PR in this repo and we add the changelog and schema changes early, we have to painstakingly resolve merge conflicts on those over time because we're all editing the same file. Is there any way we could find a pattern that didn't require editing a monolithic file together?

I think the best way would be to have a folder for future changelog and schema changes respectively, which each have a collection of individual files for the changelog and schema changes for the next release. Then the release process would take care of squashing together all the files we have in those folders each release. This would have two benefits:

• No more merge conflicts by all editing the same files; each change would have its own file
• If things change while you're working on your PR, it is very easy to edit your expected schema and changelog changes
• The file will only exist in the folder on main once the PR is merged, meaning if a PR lasts beyond the release it was created for, we don't have to worry about continuously moving the change back up to next when we resolve merge conflicts

However I am open to any other suggestions that would help resolve the toil of resolving merge conflicts in these files.

[trisch-me]

I have a workaround - I add my change to the changelog not to the end but before the last entry (will not work if you are the first one after release but this happens rare). In this case you will not have a conflict as changes appear in different parts of file.

[pyohannes]

There's the possibility to automatically create release notes (with change logs) from the commit history: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes

However, this requires discipline with naming and labeling. Also, it would still be some manual work to get the changelogs from different releases into a single file.

[joaopgrassi]

I like how they have it in the collector repo https://github.com/open-telemetry/opentelemetry-collector/blob/main/CONTRIBUTING.md#when-to-add-a-changelog-entry

Perhaps we can do something similar?

For the schema files I'm not sure we can do it in a automated way🤔

[braydonk]

I like how they have it in the collector repo

This is what I was hoping as well. It is a much nicer system. I think it would be reasonable to come up with something similar for schema-next.yaml, given that it is already a structured document we could merge other structured documents into the main one. I feel like it's a solvable problem, but there's no existing tooling for it yet.

[braydonk]

There's the possibility to automatically create release notes (with change logs) from the commit history

I like this in other repos I'm a part of, however the CHANGELOG.md seems to require significantly more detail than release notes so I'm not sure if there is an easy automated way to encode all of that information into a commit.

[joaopgrassi]

I will try and work on adopting https://github.com/open-telemetry/opentelemetry-go-build-tools/tree/main/chloggen in the semconv repo.