RELEASE NOTES: Difference between revisions

(6 intermediate revisions by the same user not shown)

Line 1:

You've studied the [[Git/hacks]] and built a ton of features, fixes, and updates to your codebase in a sprint worthy of Usain Bolt ~~[[File:Hussein Bolt.png|thumb]]~~. Now it's time to create some release notes - which in the tradition of open source is stored in the RELEASE_NOTES file of your project.

[[File:Hussein Bolt.png|thumb]]

You've studied the [[Git/hacks]] and built a ton of features, fixes, and updates to your codebase in a sprint worthy of Usain Bolt. Now it's time to create some release notes - which in the tradition of open source is stored in the RELEASE_NOTES file of your project.

Since your team follows the best practices of writing good commit comments and also creating appropriate branches and pull requests, then it's a simple matter of letting '''[[git]]''' tell you what's in the release. Of course you can amend or add to it as needed.

First, study [[git/log]] for how to use the log command.

<ol>

<li> First, study [[git/log]] for how to use the log command.</li>

<li> Optionally, if you are adopting a formal process for the first time and do not want to go all the way back in time to publish your release notes, you might need to figure out the last parent branch where you want to 'start' your notes.

See [[Git/hacks#How_did_I_get_here?]] </li>

<li> Iterate on git log commands to find the one that works for you. E.g. <code>git log --stat</code> or <code>git log --pretty</code> between the prior branch/tag and HEAD (or current release tag)</li>

</ol>

In the final analysis, use '''<tt>--no-merges</tt>'''<br>

to show the whole commit history, but skip any merge commits so that the Release Notes are not cluttered with workflow items.

<code>git log --no-merges --format="%(decorate:prefix=,suffix=%n,tag=%n## Meza ,separator= )* %h (%as) %an: %s %b" 39.5.0...HEAD > RELEASE_NOTES-UPDATE.md</code> generates a pretty good update to the RELEASE_NOTES since v39.5.0 which is then manually reviewed and edited to clarify commit messages; add links etc.

== Current Method ==

Using a combination of <code>git log</code> to produce the Notes

plus <code>sed</code> to convert commit SHAs to GitHub links

and convert Issue references to GitHub Issue links, we get a pretty good RELEASE NOTES for any given range of commits.

By naming the file .md, and creating the links in markdown format, we can see the links as clickable in both GitHub and in VSCode with Markdown preview, bringing interactivity to the notes where developers want to drill down into details.

<ol>

Bash example 'one-liner'<syntaxhighlight lang="bash">

~~<li> find the last parent branch~~

export START=43.25.11; \

~~see~~ [[~~Git~~/~~hacks~~#~~How_did_I_get_here~~?]] </li>

export END=43.29.1; \

<li> do a ~~<code>git log~~ --~~stat</code> or <code>git log~~ --~~pretty</code> between the prior branch and HEAD</li>~~

git log --no-merges --name-status --format="%(decorate:prefix=,suffix=%n,tag=%n## Meza ,separator= )* %h (%as) %an: %s %b" $START..$END \

~~</ol>~~

| sed -E 's/\* ([0-9a-f]{8})/\* [\1](https:\/\/github.com\/freephile\/meza\/commit\/\1)/g' \

| sed -E 's/Issue # ?([0-9]{1,4})/Issue [#\1](https:\/\/github.com\/freephile\/meza\/issues\/\1)/Ig' \

> RELEASE_NOTES-$END.md

</syntaxhighlight>We formalized it and turned it into a script: [https://github.com/freephile/meza/blob/main/src/scripts/generate-release-notes.sh generate-release-notes.sh]

See Meza [https://github.com/freephile/meza/blob/main/RELEASE_NOTES-43.29.1.md RELEASE_NOTES-43.29.1.md] as an example of the output.

== Bonus feature ==

On-wiki, using the [[mw:Extension:ExternalContent|ExternalContent]] extension, we can embed remote markdown files from source repositories like GitHub. Therefore, we can have on-wiki content that displays rendered RELEASE NOTES markdown. See [[Meza 43.x]] as an example.

~~'''<tt>--no-merges</tt>'''<br>~~

== In MediaWiki ==

~~Show~~ the ~~whole commit history~~, ~~but skip any merge commits so that the~~ Release Notes are ~~not cluttered~~ with ~~workflow items~~.

In the MediaWiki project, Release Notes are a hybrid mix of "CHANGELOG" (what I would call a pure version control / issue tracker list) plus "Product" notes about new features, deprecations and the important highlights of the release. For each release, there is a file produced with the naming convention of RELEASE-NOTES-''1.NN'' with all prior contents stored chronologically in the HISTORY file.

See [[mediawikiwiki:Release_notes/1.43|on-wiki RELEASE NOTES for version 1.43]] and the [https://github.com/wikimedia/mediawiki/blob/05631d4fe4eeb32fac725072a8e57b61f3ebd7b9/RELEASE-NOTES-1.43 RELEASE-NOTES-1.43] file in the repository.

See Also: https://www.mediawiki.org/wiki/Release_notes/data

@@ Line 1: / Line 1: @@
-You've studied the [[Git/hacks]] and built a ton of features, fixes, and updates to your codebase in a sprint worthy of Usain Bolt [[File:Hussein Bolt.png|thumb]]. Now it's time to create some release notes - which in the tradition of open source is stored in the RELEASE_NOTES file of your project.
+[[File:Hussein Bolt.png|thumb]]
+You've studied the [[Git/hacks]] and built a ton of features, fixes, and updates to your codebase in a sprint worthy of Usain Bolt. Now it's time to create some release notes - which in the tradition of open source is stored in the RELEASE_NOTES file of your project.
 Since your team follows the best practices of writing good commit comments and also creating appropriate branches and pull requests, then it's a simple matter of letting '''[[git]]''' tell you what's in the release. Of course you can amend or add to it as needed.
-First, study [[git/log]] for how to use the log command.
+<ol>
+<li> First, study [[git/log]] for how to use the log command.</li>
+<li> Optionally, if you are adopting a formal process for the first time and do not want to go all the way back in time to publish your release notes, you might need to figure out the last parent branch where you want to 'start' your notes.
+See [[Git/hacks#How_did_I_get_here?]] </li>
+<li> Iterate on  git log commands to find the one that works for you. E.g. <code>git log --stat</code> or <code>git log --pretty</code> between the prior branch/tag and HEAD (or current release tag)</li>
+</ol>
+In the final analysis, use '''<tt>--no-merges</tt>'''<br>
+to show the whole commit history, but skip any merge commits so that the Release Notes are not cluttered with workflow items.
+<code>git log --no-merges --format="%(decorate:prefix=,suffix=%n,tag=%n## Meza ,separator= )* %h (%as) %an: %s %b" 39.5.0...HEAD > RELEASE_NOTES-UPDATE.md</code> generates a pretty good update to the RELEASE_NOTES since v39.5.0 which is then manually reviewed and edited to clarify commit messages; add links etc.
+== Current Method ==
+Using a combination of <code>git log</code> to produce the Notes
+plus <code>sed</code> to convert commit SHAs to  GitHub links
+and convert Issue references to GitHub Issue links, we get a pretty good RELEASE NOTES for any given range of commits.
+By naming the file .md, and creating the links in markdown format, we can see the links as clickable in both GitHub and in VSCode with Markdown preview, bringing interactivity to the notes where developers want to drill down into details.
-<ol>
+Bash example 'one-liner'<syntaxhighlight lang="bash">
-<li> find the last parent branch
+export START=43.25.11; \
-see [[Git/hacks#How_did_I_get_here?]] </li>
+export END=43.29.1; \
-<li> do a <code>git log --stat</code> or <code>git log --pretty</code> between the prior branch and HEAD</li>
+git log --no-merges --name-status --format="%(decorate:prefix=,suffix=%n,tag=%n## Meza ,separator= )* %h (%as) %an: %s %b" $START..$END \
-</ol>
+| sed -E 's/\* ([0-9a-f]{8})/\* [\1](https:\/\/github.com\/freephile\/meza\/commit\/\1)/g'  \
+| sed -E 's/Issue # ?([0-9]{1,4})/Issue [#\1](https:\/\/github.com\/freephile\/meza\/issues\/\1)/Ig' \
+> RELEASE_NOTES-$END.md
+</syntaxhighlight>We formalized it and turned it into a script: [https://github.com/freephile/meza/blob/main/src/scripts/generate-release-notes.sh generate-release-notes.sh]
+See Meza [https://github.com/freephile/meza/blob/main/RELEASE_NOTES-43.29.1.md RELEASE_NOTES-43.29.1.md] as an example of the output.
+== Bonus feature ==
+On-wiki, using the [[mw:Extension:ExternalContent|ExternalContent]] extension, we can embed remote markdown files from source repositories like GitHub. Therefore, we can have on-wiki content that displays rendered RELEASE NOTES markdown. See [[Meza 43.x]] as an example.
-'''<tt>--no-merges</tt>'''<br>
+== In MediaWiki ==
-Show the whole commit history, but skip any merge commits so that the Release Notes are not cluttered with workflow items.
+In the MediaWiki project, Release Notes are a hybrid mix of "CHANGELOG" (what I would call a pure version control / issue tracker list) plus "Product" notes about new features, deprecations and the important highlights of the release. For each release, there is a file produced with the naming convention of RELEASE-NOTES-''1.NN'' with all prior contents stored chronologically in the HISTORY file.
+See [[mediawikiwiki:Release_notes/1.43|on-wiki RELEASE NOTES for version 1.43]] and the [https://github.com/wikimedia/mediawiki/blob/05631d4fe4eeb32fac725072a8e57b61f3ebd7b9/RELEASE-NOTES-1.43 RELEASE-NOTES-1.43] file in the repository.
 See Also: https://www.mediawiki.org/wiki/Release_notes/data