This is a pretty popular issue we currently have with the changelog system, especially during around the time of stable release. This thread will serve as a way to try to come up with ideas to fix the current system.
How it works currently
The changelog is a file that resides in Resources/Changelog/Changelog.yml (or any of the other). It is automatically edited by SS14.Changelog bot by creating part files and then after a set period merging them (The parts folder exists as a way to add a new changelog manually without needing to merge an empty PR or something. You just create a yml file excluding everything but the ID field)
The current issue
This system worked pretty well when we did all our server work directly on master, misspelling in the changelog file (or one against the changelog guidelines)? No issue, just edit it and publish. Forgot to add an entry? Just create a part file and publish after the bot takes care of it!
Essentially, editing a changelog on master is:
Make a PR doing the fix. (Editing an existing changelog or adding a new one)
Merge.
Publish to get it to appear.
This system is actually not an issue on master at all and works just fine!
And then stable came along, due to the fact that the changelog file is tracked by git, This makes it a little annoying to just edit the changelog file. As the “just edit” process it now
Make a PR doing the fix on stable. (Due to the bot not tracking the stable branch, this will involve needing to manually edit the changelog file (more later))
Merge.
Merge stable back to master.
Solve conflicts (there will be some)
Publish to get it to appear.
A lot more steps, honestly this part is more of a chore if anything… my issue is how to deal with conflicts back to master.
This is an issue because of changelog entries using “ID’s”. The changelog bot automatically increments this by one for every changelog. I am not sure what happens if we have duplicate id’s on a changelog entry but I would prefer to avoid an ID clash. It will be quite common to encounter a merge conflict or accidentally create clashing ID’s.
This is why I dont currently feel comfortable whitelisting the changelog bot to act within the stable branch.
I also admitibly myself don’t really like having to publish the server for the simple act of editing the changelog file.
My ideas for solving it
SS14.Changelog somehow handles this
Maybe it does the “stable merge” back automagically? And increments all other id’s above it by one automatically? I don’t think this has implications of causing merge issues? But feel free to correct me.
Still has the issue of “publish needed to edit a changelog”
Probably the simplest to implement?
Some kind of extra service that does not rely on git (WEB DEVELOPMENT AAAAAAA)
Something like ss14.changelog having a nice webpage to edit/add/remove entries
Client (Will need content side http requests implemented) or server (blursed imo to proxy this to the client) grab the changelog file from the webpage to show off in the UI.
The requester will tell its version to the service in order to get the latest changelogs of its version
Allows us to edit changelogs whenever without publish
Instead of Ids for each changelog entry we can maybe use the git hash for that PR so it’s unique and easy to find.
And somehow not make the changelog one giant file that will conflict. But I guess having a separate text file for each entry would be messy as well.
An issue with making the changelog’s handling more external is that this puts additional burder on downstreams who will all have to operate their own extra service, and might also not work well in/for dev testing. Keeping the changelog wholly internal to project files would be ideal.
What if we just don’t even HAVE a changelog.yml, only part files? Every time a changelog is needed, it gets assembled from the partfiles. Or perhaps just once when the client starts, for performance reasons. No need for it to be able to change while the client is running, ever.
And we could avoid shifting IDs up when we insert a new one by adding decimals to the ID. Then it would still be possible to sort them. Don’t see much of a potential conflict with that solution, and even if there is, and multiple subsequently inserted entries get shifted a bit out of order, that’s probably irrelevant in the great scheme of things if they are about in the correct spot.
But getting rid of changelog.yml would mean that there would be very little chance for merge conflicts when either adding of modifying/deleting part files
After thinking this over I think the best solution is to just have a separate file for stable. As part of the release process, the changelogs from master would get merged into the stable file, going into a single massive entry put at time of release.
On another note, we should really take these changelogs and put them on Discourse or even the website at some point.