RELEASE NOTES: Difference between revisions

(5 intermediate revisions by the same user not shown)

Line 6:

<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 say~~ the last parent branch where you want to 'start' your notes.

<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>

Line 14:

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

<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.

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

export START=43.25.11; \

export END=43.29.1; \

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

| 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.

== In MediaWiki ==

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 6: / Line 6: @@
 <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 say the last parent branch where you want to 'start' your notes.
+<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>
@@ Line 14: / Line 14: @@
 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
+<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.
+Bash example 'one-liner'<syntaxhighlight lang="bash">
+export START=43.25.11; \
+export END=43.29.1; \
+git log --no-merges --name-status --format="%(decorate:prefix=,suffix=%n,tag=%n## Meza ,separator= )* %h (%as) %an: %s %b" $START..$END \
+| 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.
+== In MediaWiki ==
+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