C4-PlantUML/.scripts/HowToCreateANewRelease.md

How to create a new release (WIP)

The idea is to

• create a new release in the "release/$release_version" branch (tagged with $release_version and latest)
• and a MR that the master branch can be updated with next beta version
• create in PlantUML/PlantUML-stdlib a MR with the released version

0. Preparation

The process requires following 3 versions:

• $release_version: version which should be created (e.g. v2.6.0)
• $next_version: version of the next beta which should be stared as soon the release is created (e.g. v2.7.0).
  The master branch will be updated with a beta1 of this version and C4Version() returns 2.7.0beta1.
  If it is unknown/undefined it is calculated via the release_version. It is the next patch (release patch!=0) or subversion (release patch==0).
• $deployed_version: this is the next "plantuml(/plantuml-stdlib)" version which should be updated with this release (e.g. "V1.2023.2")
  If it is unknown/undefined it is calculated via the running PlantUML web service

0.0 Create a new issue with the title Release $release_version (e.g. Release v2.6.0)

and a body like in https://github.com/plantuml-stdlib/C4-PlantUML/issues/248

0.1 Check that all open issues of the related $release_version milestone are fixed

0.2 Check that all other open changes are done

Update copyright year, contrib files, URLS, .... if required

0.* ...

0.x Check which is the next released version of the PlantUML(/PlantUML-stdlib)

it is used as $deployed_version and written in the released README.md
If it is unknown it can be calculated via CalculateDeployedVersion (details see below)

1. create new release in branch release/$release_version (based on master)

Atm following steps are semi-automated and can be executed in a bash shell:

1.0. define the relevant versions as environment variabels and create the release/$release_version branch

(in following sample the release_version = v2.6.0; next_version = v2.7.0 and deployed_version = V1.2022.15)

export release_version=v2.6.0
export next_version=v2.7.0
export deployed_version=V1.2022.15

If the deployed_version is unknown it can be calculate via following (don't forget to set the environment variable after the call)

python ./.scripts/transform_files.py CalculateDeployedVersion

As soon all versions are defined the release/$release_version branch (e.g. release/v2.6.0) can be created based on master branch

git pull
git checkout master
git branch release/$release_version
git checkout release/$release_version

1.1. Update C4Version() in C4.puml with the new release (e.g. 2.6.0; without v)

python ./.scripts/transform_files.py UpdateC4WithReleaseVersion

1.2. Update all include paths and create a release version of the README.md

Following script calls

• Update all include paths with the release version tag based branch
• Update includes of all image urls with the release version tag based in *.md (after that images displays the correct C4Version() number and uses only the release-tag path in all includes)
• Update README.md with the new release header and title (based on the readme_release_header.txt template)

python ./.scripts/transform_files.py UpdateAllIncludes
python ./.scripts/transform_files.py UpdateAllImages
python ./.scripts/transform_files.py ReplaceREADMEHeader

These changes can/should be checked and if everything is ok it can be committed.

Following commit all changes and tag it locally with $release_version (e.g. v2.5.0)

git checkout release/$release_version
git add -u *.md
git add -u *.puml
git add -u **/*.md
git add -u **/*.puml
git commit -m "Create release (branch) $release_version"
git tag "$release_version"

And if everything is ok it can be pushed too

git checkout release/$release_version
git push -u origin release/$release_version

2. Create Release $release_version (e.g. Release v2.6.0) itself

This is done manually (incl. an additional check...)

Important: As soon the release is finished check that

• 'latest' tag is re-assigned to the new release branch
• and '$release_version' tag is assigned to the new release branch

As soon the version is released the release branch has to be write protected

3. Update master branch with $next_version beta1 version

3.1. create a start-$next_version-beta1 branch (e.g. start-v2.7.0-beta1) based on master branch

git pull
git checkout master
git branch start-$next_version-beta1
git checkout start-$next_version-beta1

Following script update C4Version() in C4.puml with the next beta release (e.g. 2.7.0beta1; without v)

python ./.scripts/transform_files.py UpdateC4WithNextBeta

Following commit all changes

git checkout start-$next_version-beta1
git add -u C4.puml
git commit -m "Update version with first beta of $next_version ($release_version was created based on previous commit)"

And if everything is ok it can be pushed too

git checkout start-$next_version-beta1
git push -u origin start-$next_version-beta1

3.2. Create a MR into master

This is done manually (incl. an additional check...)

4. Create in PlantUML/PlantUML-stdlib a MR based on release/$release_version branch

!!! CHECK that the correct release branch is activated !!!

It is assumed that following calls are started in "C4-PlantUML repository" folder (and not in the "plantuml-stdlib repository" folder)

The process requires following information too:

• $deploy_repository_folder: folder with the local PlantUML/PlantUML-stdlib git repositiory.
  E.g. if it is parallel to the C4-PlantUML repository the it could be ../plantuml-stdlib.

4.1. create in a PlantUML/PlantUML-stdlib fork a C4$release_version branch (e.g. C4v2.6.0)

export release_version=v2.6.0
export next_version=v2.7.0
export deployed_version=V1.2022.15

export deploy_repository_folder=../plantuml-stdlib

git pull
git checkout release/$release_version

git -C $deploy_repository_folder pull
git -C $deploy_repository_folder checkout master
git -C $deploy_repository_folder branch C4$release_version
git -C $deploy_repository_folder checkout C4$release_version

4.2. prepare the C4_*.puml, themes and README.md files

python ./.scripts/transform_files.py CreatePlantUMLStdlibC4Folder $deploy_repository_folder/stdlib/C4

4.3. Commit changes with comment "Update C4-PlantUML to $release_version"

git -C $deploy_repository_folder add -u C4/**
git -C $deploy_repository_folder commit -m "Update C4-PlantUML to $release_version"

4.4. create a MR "Update C4-PlantUML to $next_version"

This is done manually (incl. an additional check...)