Freephile Wiki

RELEASE NOTES: Difference between revisions

Browse history interactively
← Older edit
VisualWikitext
No edit summary
describe and link to Meza 43.x
 
(8 intermediate revisions by the same user not shown)
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]]
[[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.
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.
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.


<ol>
<ol>
<li> find the last parent branch
<li> First, study [[git/log]] for how to use the log command.</li>
see [[Git/hacks#How_did_I_get_here?]] </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.
<li> do a <code>git log --stat</code> or <code>git log --pretty</code> between the prior branch and HEAD</li>
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>
</ol>


You'll get output like the following:
In the final analysis, use '''<tt>--no-merges</tt>'''<br>
<pre>
to show the whole commit history, but skip any merge commits so that the Release Notes are not cluttered with workflow items.
git log --stat feature-kibana..HEAD
commit ab10ebe10fa294f4a8ce456269107281f2e2de18 (HEAD -> qb-1.43, origin/qb-1.43)
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Fri Jan 17 19:08:51 2025 +0000


    Maintenance Script update (missed these)
<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.
   
    Convert script calls to go through executable
    'maintenance/run'
    For extensions, use the class naming pattern
    'Extension:ClassName'
    Fixes Issue #142


src/playbooks/cleanup-upload-stash.yml    | 2 +-
== Current Method ==
src/roles/cron/templates/runAllJobs.php.j2 | 2 +-
Using a combination of <code>git log</code> to produce the Notes
2 files changed, 2 insertions(+), 2 deletions(-)


commit ca1791040ebf7ea5e7ff4cef04f6c3ef2d56f2d2
plus <code>sed</code> to convert commit SHAs to  GitHub links
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Fri Jan 17 19:01:19 2025 +0000


    Finish Maintenance Script update
and convert Issue references to GitHub Issue links, we get a pretty good RELEASE NOTES for any given range of commits.
   
    Convert script calls to go through executable
    'maintenance/run'
    For extensions, use the class naming pattern
    'Extension:ClassName'
    Fixes Issue #142


src/playbooks/cleanup-upload-stash.yml                  |  2 +-
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.
src/roles/mediawiki/tasks/main.yml                      |  4 ++--
src/roles/mediawiki/templates/elastic-build-index.sh.j2 |  6 +++---
src/roles/mediawiki/templates/refresh-links.sh.j2      |  6 +++---
src/roles/mediawiki/templates/smw-rebuild-all.sh.j2    |  2 +-
src/roles/meza-log/templates/server-performance.sh.j2  |  2 +-
src/roles/update.php/tasks/main.yml                    |  8 ++++----
src/roles/verify-wiki/tasks/import-wiki-sql.yml        |  2 +-
src/roles/verify-wiki/tasks/init-wiki.yml              |  2 +-
src/scripts/unite-the-wikis.sh                          | 14 +++++++-------
10 files changed, 24 insertions(+), 24 deletions(-)


commit d624f7b4fbed42033dd8b6da3e786f9c1de53340
Bash example 'one-liner'<syntaxhighlight lang="bash">
Author: Greg Rundlett <greg.rundlett@gmail.com>
export START=43.25.11; \
Date:   Thu Jan 16 23:48:54 2025 +0000
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]


    A new tool to inspect the git repos on the controller
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.


src/scripts/listExtensionRepos.sh | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
== Bonus feature ==
1 file changed, 75 insertions(+)
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.


commit e267f14854957206ba556812038c357e27db0116
== In MediaWiki ==
Author: Greg Rundlett <greg.rundlett@gmail.com>
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.
Date:  Thu Jan 16 23:48:12 2025 +0000


    Update the Update.php role for new Maintenance script ops
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.
   
    Issue #142


src/roles/update.php/tasks/main.yml | 6 +++---
See Also: https://www.mediawiki.org/wiki/Release_notes/data
1 file changed, 3 insertions(+), 3 deletions(-)
 
commit 9e4de5e18ad148ff47660c6c22b5dbf6ace5c940
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Thu Jan 16 23:46:57 2025 +0000
 
    Update maintenance scripts
   
    Server Performance logging/reporting role
    (Probably needs to be eliminated altogether)
    Issue #142
 
src/roles/meza-log/templates/server-performance.sh.j2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
 
commit 278c394ee70a00d86abcf13f434f6677723436b6
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Thu Jan 16 23:45:38 2025 +0000
 
    Update maintenance scripts
   
    showSiteStats and refreshLinks
    Issue #142
 
src/roles/mediawiki/templates/refresh-links.sh.j2 | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
 
commit 57c9bb20231e76fed948d22ea93714cff24d53c6
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Thu Jan 16 23:44:01 2025 +0000
 
    Disable metastore maintenance
   
    All maintenance needs to be refactored
    Issue #142
    Also, this may be affected by upgrading to SMW 5.x
    Issue #136
 
src/roles/mediawiki/tasks/main.yml | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
 
commit 7ad66760bc98bfdf95f7774ad920c669510ca784
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Thu Jan 16 23:42:08 2025 +0000
 
    Prefer source in composer managed extensions
   
    Use the --prefer-source option to composer
    Eliminate the duplicate composer run
    Eliminate the removal of a non-existant SMW file (IdeAliases.php)
    needed for Issue #136
 
src/roles/mediawiki/tasks/main.yml | 24 ++----------------------
1 file changed, 2 insertions(+), 22 deletions(-)
 
commit f87b92b261035b4e8f91a169ecf9b286303de61c
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Thu Jan 16 23:32:29 2025 +0000
 
    Update maintenance scripts for MediaWiki 1.40
   
    Fixes Issue #142
 
src/roles/cron/templates/runAllJobs.php.j2 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
 
commit 4ca775d65b3f64907dd87990af28073d454702fa
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Thu Jan 16 22:56:48 2025 +0000
 
    Update MezaCoreExtensions.yml for REL1_43
   
    Use full enableSemantics() call to fix URL pattern
    Switch to gerrit because GitHub seems to throttle
    SemanticDrilldown 3.05 -> dev-master
    SemanticScribunto 2.2.0 -> dev-master
    add quotes on SemanticDrilldown version spec
    add quotes on SubPageList version spec
 
config/MezaCoreExtensions.yml | 215 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------------------------------------------------------------------------------------------------
1 file changed, 104 insertions(+), 111 deletions(-)
 
commit e2873948a30a02fb56a8be6d40181f76101fad1c
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Fri Jan 10 17:45:00 2025 +0000
 
    Create a variable named php_memory_limit defaulting to 128M
   
    PHP normally defaults to 128M so we also default to that.
    Templated in the php.ini template of the apache-php role.
    Fixes issue #151
 
config/defaults.yml                      | 1 +
src/roles/apache-php/templates/php.ini.j2 | 2 +-
2 files changed, 2 insertions(+), 1 deletion(-)
 
commit 51c89233b3279fbdd76c371cbdd5f9b17552d614
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Wed Jan 8 01:39:19 2025 +0000
 
    Enable SemanticCompoundQueries
   
    Was 2.2.0
    Now 3.x-dev (same as dev-master)
    Issue #140
 
config/MezaCoreExtensions.yml | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
 
commit d2a87e79e3f039f7c81cc2ca091959698a11d99c
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Wed Jan 8 00:43:17 2025 +0000
 
    Use SubPageList dev-master
   
    Fixes issue #138
 
config/MezaCoreExtensions.yml | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
 
commit ca17aac64a4c1cd83be7ea4f22ac6b2732bdce06
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Tue Jan 7 21:38:15 2025 +0000
 
    Disable or update non-working skins
   
    These skins need a version adjustment or update
    to work with REL1_43
    - Tweeki
    - Medik
   
    Use tags/v4.39.1 for Tweeki
    Issue #136
 
config/MezaCoreSkins.yml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
 
commit cde7d8cfaa866bbcba6de5b32b34f1d94b1134e6
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Tue Jan 7 21:09:29 2025 +0000
 
    Disable non-working extensions
   
    These extensions do not work, or need a version adjustment,
    to be compatible with REL1_43 and SMW 5.x
    - SemanticCompoundQueries
    - SemanticDependencyUpdater
    - SemanticDrilldown
    - SemanticExtraSpecialProperties
    - SemanticResultFormats
    - SemanticScribunto
    - SubPageList
 
config/MezaCoreExtensions.yml | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------------------------------------------------
1 file changed, 71 insertions(+), 70 deletions(-)
 
commit 36567d8330bef1a28d923fd0f351f7ef6e26bdd8
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Tue Jan 7 21:04:38 2025 +0000
 
    Switch SMW to dev-master
   
    Addresses Issue #137
    composer show -a mediawiki/semantic-media-wiki
    shows all available composer versions
 
config/MezaCoreExtensions.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
 
commit d7d6a88ecebedf8eb2a2d476d26d937696ba2809
Author: Greg Rundlett <greg.rundlett@gmail.com>
Date:  Tue Jan 7 17:33:33 2025 +0000
 
    Upgrade to REL1_43
   
    Fixes Issue #136
    set meza_repository_url to use freephile/meza
    set mediawiki_version for core
    set mediawiki_default_branch (for extensions)
    set php_ius_version to php81
 
config/defaults.yml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
</pre>
 
I've written up fancier routines for this, but every time they're lost to the client where I've implemented them so this article is a stub to record and improve on the existing practices. See for instance: https://www.mediawiki.org/wiki/Release_notes/data


[[Category:Best Practices]]
[[Category:Best Practices]]
Retrieved from "https://wiki.freephile.org/wiki/RELEASE_NOTES"