build release procedure updates to include docs in release tag

[jodygarnett]

Updated the build release instructions to cover the creation of new markdown changelog page.

This needs to occur earlier in the release process so that the documentation is included in the release tag.

Also noted that the docs were built after the war, and thus were not including the online help when requested with the docs profile.

See also: #7411 to publish docs when a release is tagged.

change log creation

Please see doing a release.md for proccess of using git note in the creation of a change log.

👍🏻 This approach allows pull requests to be back ported, with an optional "change log" associated with the squashed commit. This way the change log when generated for each branch includes the appropriate information.

👎🏻 Keep in mind that git notes, like git tags, are shared between all repositories (and do not really offer a smooth conflict resolution mechanism).

[jodygarnett]

The alternative to creating a changelog when tagging a new release; is to create one just after each release is made (for the upcoming release).

In this approach the docs would have a changelog visible for the upcoming release; it could have a note at the top indicating when the release was scheduled for.

!!! note title="Scheduled Release"
    
    To help test here new features please download a nightly build.
    Release scheduled for December 2023

[jodygarnett]

This can be back ported to 4.2.x and 3.12.x

[jodygarnett]

This may need to be rebased and tested again; please let's review these build changes before they bit-rot :)

[jodygarnett]

@josegar74 I have updated release example version 4.4.1 latest release.

[jodygarnett]

@josegar74 this is the PR that I would like to see included, and troubleshooted during your release process.
It has gone into conflict again; but I am willing to work with you to make sure these changes are made.

[jodygarnett]

I have recreated this PR from main resulting in a clean commit history

[josegar74]

I'm not sure about this, is not the same as described in https://github.com/geonetwork/core-geonetwork/pull/7412/files#diff-afba6fb6c27ca0266f6c91620aac83e1f176672301fd1c3236755cd435247617R80 ?

[josegar74]

Probably I'm misunderstanding about including docs in the release tag. Is the intention to include the docs in the war file?

I tried:

mvn clean install -DskipTests -Pwar -Pwro4j-prebuild-cache

And seems no docs included, tried also with -Pall profile, same results.

[josegar74]

Maybe can be good to use 4.4 for example instead of 4.2 (see other related variables below)

[ticheler]

The backport to 4.2.x failed:

The process '/usr/bin/git' failed with exit code 1

stderr

error: could not apply 5890c43c0d... move changes to their own folder
hint: After resolving the conflicts, mark them with
hint: "git add/rm <pathspec>", then run
hint: "git cherry-pick --continue".
hint: You can instead skip this commit with "git cherry-pick --skip".
hint: To abort and get back to the state before "git cherry-pick",
hint: run "git cherry-pick --abort".

stdout

CONFLICT (rename/delete): docs/changes4.4.0-0.txt renamed to docs/changes/changes4.4.0-0.txt in 5890c43c0d (move changes to their own folder), but deleted in HEAD.
CONFLICT (rename/delete): docs/changes4.4.1-0.txt renamed to docs/changes/changes4.4.1-0.txt in 5890c43c0d (move changes to their own folder), but deleted in HEAD.

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-4.2.x 4.2.x
# Navigate to the new working tree
cd .worktrees/backport-4.2.x
# Create a new branch
git switch --create backport-7412-to-4.2.x
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick 5890c43c0d767eea4c27d47fb64e0f894a1f7262,caa9e32c1eae9f44b78f873f8c2fcbdf765191cf,5e340d13ce1a6bb8258e7abcc427ef908ec86e24,fd30bc92111d815227d74680f3532934fdc90de8,a5032d901afb18cb7499dd10acd3111ce60d724e,16b9737d41ca42329c1baf8a9ad81f593b038244,88e1942f11d29f32b2f49808561e74158dbcf8eb,93edc607756f6b21e5fe15303dd12eb263ba1219,cd6986b86eee3ec8b86bf8533f862c86922af3bd
# Push it to GitHub
git push --set-upstream origin backport-7412-to-4.2.x
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-4.2.x

Then, create a pull request where the base branch is 4.2.x and the compare/head branch is backport-7412-to-4.2.x.