You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We recently split the changelog and release notes to their own documents at #10031 because the changelog was getting really heavy and hard to follow. We decided to split the release notes to their own documents also to follow the keep a changelog "standard" for managing the changelog document.
Another goal was to make the formatting in these documents so that we can easily create the new releases at GitHub by copy-pasting the contents from these two documents to the release page.
Problem
This brings another problem regarding the patch releases. The release notes is mostly meant for the major/minor releases for the implementor to follow when updating between the major/minor versions. Most of the times we don't have such notes for the patch releases as simply upgrading the gem version and running the upgrade commands should be enough.
v0.27.1 is a good example of a typical patch release which does not require any additional notes, only the typical stuff.
But what if we need to add e.g. one time actions for patch releases in case we fixed some bug that requires e.g. data update in the database?
I would not like to make another RELEASE_NOTES.md document for each and every patch release as this would become quite redundant. And I would not want to edit the main RELEASE_NOTES.md because someone might be browsing these through GitHub because they can show up e.g. in search results.
We also don't want to add any 2nd level headings for the versions in that document because that would break the copy-paste approach when creating the release page.
Solution
My suggestion would be to just add the relevant notes at the relevant sections of the RELEASE_NOTES.md to maintain the whole notes for that major/minor release in one place. E.g. if someone wants to upgrade from 0.26.4 directly to 0.27.1, they would just have one RELEASE_NOTES.md to follow (the one at GitHub).
Then, we would do a simple git diff v0.27.0 v0.27.1 RELEASE_NOTES.md when creating the GitHub patch release and add the relevant points shown by the diff to the release notes manually (note that this command does not work for the previous releases because we just introduced this file but you can test it out with the CHANGELOG.md). This requires a bit of manual formatting but I guess it would be a reasonable middle ground so that we can maintain the actual notes in one place.
Also to note that the pointed out problem is not something that we need to do for every patch release, this should be rather rare occasion. But sometimes it may be necessary.
OK great, so what's the point?
I would like to reach a conclusion on how to handle this and document this to the Releasing new versions documentation.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
Background
We recently split the changelog and release notes to their own documents at #10031 because the changelog was getting really heavy and hard to follow. We decided to split the release notes to their own documents also to follow the keep a changelog "standard" for managing the changelog document.
Another goal was to make the formatting in these documents so that we can easily create the new releases at GitHub by copy-pasting the contents from these two documents to the release page.
Problem
This brings another problem regarding the patch releases. The release notes is mostly meant for the major/minor releases for the implementor to follow when updating between the major/minor versions. Most of the times we don't have such notes for the patch releases as simply upgrading the gem version and running the upgrade commands should be enough.
v0.27.1 is a good example of a typical patch release which does not require any additional notes, only the typical stuff.
But what if we need to add e.g. one time actions for patch releases in case we fixed some bug that requires e.g. data update in the database?
I would not like to make another
RELEASE_NOTES.md
document for each and every patch release as this would become quite redundant. And I would not want to edit the mainRELEASE_NOTES.md
because someone might be browsing these through GitHub because they can show up e.g. in search results.We also don't want to add any 2nd level headings for the versions in that document because that would break the copy-paste approach when creating the release page.
Solution
My suggestion would be to just add the relevant notes at the relevant sections of the
RELEASE_NOTES.md
to maintain the whole notes for that major/minor release in one place. E.g. if someone wants to upgrade from 0.26.4 directly to 0.27.1, they would just have oneRELEASE_NOTES.md
to follow (the one at GitHub).Then, we would do a simple
git diff v0.27.0 v0.27.1 RELEASE_NOTES.md
when creating the GitHub patch release and add the relevant points shown by the diff to the release notes manually (note that this command does not work for the previous releases because we just introduced this file but you can test it out with theCHANGELOG.md
). This requires a bit of manual formatting but I guess it would be a reasonable middle ground so that we can maintain the actual notes in one place.Also to note that the pointed out problem is not something that we need to do for every patch release, this should be rather rare occasion. But sometimes it may be necessary.
OK great, so what's the point?
I would like to reach a conclusion on how to handle this and document this to the Releasing new versions documentation.
Beta Was this translation helpful? Give feedback.
All reactions