diff --git a/.scripts/HowToCreateANewRelease.md b/.scripts/HowToCreateANewRelease.md new file mode 100644 index 0000000..6f4545c --- /dev/null +++ b/.scripts/HowToCreateANewRelease.md @@ -0,0 +1,144 @@ +# 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`. +- $deployed_version: this is the next "plantuml(/plantuml-stdlib)" version which should be updated with this release (e.g. "V1.2023.2") + +### 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 + +## 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`) + +```bash +export release_version=v2.6.0 +export next_version=v2.7.0 +export deployed_version=V1.2022.15 +``` + +and create the `release/$release_version` branch \(e.g. `release/v2.6.0`) based on master branch + +```bash +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`) + +```bash +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) + +```bash +python ./.scripts/transform_files.py UpdateC4WithReleaseVersion +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`) + +```bash +git checkout release/$release_version +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 + +```bash +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 + +```bash +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`) + +```bash +python ./.scripts/transform_files.py UpdateC4WithNextBeta +``` + +Following commit all changes + +```bash +git checkout start-$next_version-beta1 +git add -u C4.puml +git commit -m "Update version with first beta of $next_version ($release_version is created based on previous commit)" +``` + +And if everything is ok it can be pushed too + +```bash +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 + +- create in a PlantUML/PlantUML-stdlib fork a `C4$release_version` branch (e.g. `C4v2.6.0`) +- update the C4_*.puml and INFO file +- Commit changes with comment "Update C4-PlantUML to $release_version" +- create a MR "Update C4-PlantUML to $next_version" + +(detailed description is missing) + + diff --git a/.scripts/readme_release_header.txt b/.scripts/readme_release_header.txt new file mode 100644 index 0000000..2b74c2b --- /dev/null +++ b/.scripts/readme_release_header.txt @@ -0,0 +1,18 @@ +[![release][Release Badge]][Release Page] +[![license MIT][License Badge]][License Page] +       +[![integrated in PlantUML][Integrated Badge]][Integrated Page] +       +[![commits since][Commits Since Badge]][Commit Page] + +[Release Badge]: https://img.shields.io/badge/release-{release version}-blue +[Release Page]: https://github.com/plantuml-stdlib/C4-PlantUML/releases/{release version} +[License Badge]: https://img.shields.io/github/license/plantuml-stdlib/C4-PlantUML +[License Page]: https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/LICENSE +[Integrated Badge]: https://img.shields.io/badge/C4--PlantUML%20%20{release version}%20integrated%20in%20PlantUML%20Standard%20Library-{deploy into version}-orange +[Integrated Page]: https://plantuml.com/stdlib#062f75176513a666 + +[Commits Since Badge]: https://img.shields.io/github/commits-since/plantuml-stdlib/C4-PlantUML/latest?label=new%20unreleased%20changes%20in%20master%20branch +[Commit Page]: https://github.com/plantuml-stdlib/C4-PlantUML/commits + +# C4-PlantUML ({release version}) \ No newline at end of file diff --git a/.scripts/transform_files.py b/.scripts/transform_files.py new file mode 100644 index 0000000..48c469b --- /dev/null +++ b/.scripts/transform_files.py @@ -0,0 +1,258 @@ +#!/usr/bin/python + +# If a new version is released, version number and other topics of the source +# has to be updated. +# This script simplifies the update from master to a specific release (branch/tag) + +# IMPORTANT: +# +# - It is assumed that the script is stared in repository root with relative path +# python ./.scripts/transform_files +# +# - It is assumed that +# - "release_version" (e.g. "v2.6.0"), +# - "next_version" (e.g. "v2.7.0") and +# - "deployed_version" ... this is the next "plantuml(/plantuml-stdlib)" version +# which should be updated with this release (e.g. "V1.2023.2") +# are defined as environment variable + +# Supported transformations are +# +# - UpdateC4WithReleaseVersion +# - UpdateAllIncludes +# - UpdateAllImages +# - ReplaceREADMEHeader +# - UpdateC4WithNextBeta + +import os +import re +import sys +import glob + +import zlib +import base64 +import string + +# >>>>> plant uml decoder from ryardley/plant_uml_decoder.py +# >>>>> https://gist.github.com/ryardley/64816f5097003a35f9726aab676920d0 + +plantuml_alphabet = ( + string.digits + string.ascii_uppercase + string.ascii_lowercase + "-_" +) +base64_alphabet = string.ascii_uppercase + string.ascii_lowercase + string.digits + "+/" +b64_to_plantuml = bytes.maketrans( + base64_alphabet.encode("utf-8"), plantuml_alphabet.encode("utf-8") +) +plantuml_to_b64 = bytes.maketrans( + plantuml_alphabet.encode("utf-8"), base64_alphabet.encode("utf-8") +) + + +def plantuml_encode(plantuml_text): + """zlib compress the plantuml text and encode it for the plantuml server""" + zlibbed_str = zlib.compress(plantuml_text.encode("utf-8")) + compressed_string = zlibbed_str[2:-4] + return ( + base64.b64encode(compressed_string).translate(b64_to_plantuml).decode("utf-8") + ) + + +def plantuml_decode(plantuml_url): + """decode plantuml encoded url back to plantuml text""" + data = base64.b64decode(plantuml_url.translate(plantuml_to_b64).encode("utf-8")) + dec = zlib.decompressobj() # without check the crc. + header = b"x\x9c" + return dec.decompress(header + data).decode("utf-8") + + +# <<<<< plant uml decoder from ryardley/plant_uml_decoder.py + + +def read_environment_variable(env_var): + if env_var not in os.environ: + sys.stderr.write( + f"the required environment variable {env_var} is not defined\n" + ) + sys.exit(3) + return os.environ[env_var] + + +# It is assumed that "release_version", "next_version" and "deployed_version" +# are defined as environment variable +def read_environment_variables(): + global release_version + release_version = read_environment_variable("release_version") + if release_version[0] != "v": + sys.stderr.write( + f"release version {release_version} has to start with 'v' (and use a format like vX.Y.Z)" + ) + sys.exit(2) + global next_version + next_version = read_environment_variable("next_version") + global deployed_version + deployed_version = read_environment_variable("deployed_version") + + +def replace_regex_in_file(file_path, search, replace): + r = re.compile(search) + with open(file_path, "r") as file: + filedata = file.read() + filedata = r.sub(replace, filedata, 1) + with open(file_path, "w") as file: + file.write(filedata) + + +def replace_in_file(file_path, orig, replace): + with open(file_path, "r") as file: + filedata = file.read() + filedata = filedata.replace(orig, replace) + with open(file_path, "w") as file: + file.write(filedata) + + +def update_c4_release_version(): + # $c4Version is defined without starting 'v' + print( + f"updating C4Version() definition in C4.puml with new release_version {release_version[1:]} ..." + ) + replace_regex_in_file( + "C4.puml", '!\$c4Version = ".+"', f'!$c4Version = "{release_version[1:]}"' + ) + print(f"C4Version() updated") + + +def update_c4_next_beta_version(): + # $c4Version is defined without starting 'v' + print( + f"updating C4Version() definition in C4.puml with new release_version {release_version[1:]} ..." + ) + replace_regex_in_file( + "C4.puml", '!\$c4Version = ".+"', f'!$c4Version = "{next_version[1:]}beta1"' + ) + print(f"C4Version() updated") + + +def update_all_includes(): + # reference tag version is with starting 'v' + print(f"updating include paths with new tag version {release_version} ...") + files = glob.glob("./**/*", recursive=True) + for file in files: + if file.endswith(".puml") or file.endswith(".md"): + print(f" {file}") + replace_in_file( + file, + "!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/", + f"!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/{release_version}/", + ) + + print(f"include paths updated") + + +def process_url_match(m: re.Match[str]): + base = m.group("base") + out_format = m.group("format") + base64 = m.group("base64") + text = plantuml_decode(base64) + + new_path = f"!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/{release_version}/" + replaced = text.replace( + "!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/", + new_path, + ) + + if new_path not in replaced: + global found_not_replaced_include + found_not_replaced_include = True + print( + f"!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\ninclude could not be replaced in base64\n{base64}\nthe extracted source is\n{text}\n------------------------------------" + ) + updated_base64 = base64 + else: + updated_base64 = plantuml_encode(replaced) + + return f"{base}/{out_format}/{updated_base64}" + + +def replace_images_in_file(file_path): + # extract all base64 entries + r = re.compile( + "(?Phttps://www\\.plantuml\\.com/plantuml)/(?P(png|uml|svg))/(?P([^ )]*))" + ) + with open(file_path, "r") as file: + filedata = file.read() + filedata = r.sub(process_url_match, filedata) + with open(file_path, "w") as file: + file.write(filedata) + + +def update_all_images(): + # reference tag version is with starting 'v' + print( + f"updating include paths with new tag version {release_version} in images of all *.md files ..." + ) + + global found_not_replaced_include + found_not_replaced_include = False + + files = glob.glob("./**/*", recursive=True) + for file in files: + if file.endswith(".md"): + print(f" {file}") + replace_images_in_file(file) + + if found_not_replaced_include: + sys.stderr.write( + "!!!!!! not all images urls could be updated in the *.md files (details see log)\n" + ) + sys.exit(3) + + print(f"include paths in images updated") + + +def replace_readme_header(): + print(f"updating README.md with new version {release_version} and badges ...") + # remove whole part before "# C4-PlantUML" in readme + r = re.compile(r"[^\#]+# C4-PlantUML", re.M) + with open("README.md", "r") as file: + filedata = file.read() + filedata = r.sub("# C4-PlantUML", filedata) + + with open("./.scripts/readme_release_header.txt", "r") as header_file: + header = header_file.read() + header = header.replace("{release version}", release_version).replace( + "{deploy into version}", deployed_version + ) + + filedata = filedata.replace("# C4-PlantUML", header) + + with open("README.md", "w") as file: + file.write(filedata) + + print(f"release README.md updated with new version and badges") + + +if len(sys.argv) != 2: + u = "Usage: python ./.scripts/transform_files.py \n" + sys.stderr.write(u) + sys.exit(1) + +if sys.argv[0] != "./.scripts/transform_files.py": + u = "script has to be started in repository root with relative path: ./.scripts/transform_files \n" + sys.stderr.write(u) + sys.exit(1) + +read_environment_variables() + +if sys.argv[1] == "UpdateC4WithReleaseVersion": + update_c4_release_version() +elif sys.argv[1] == "UpdateAllIncludes": + update_all_includes() +elif sys.argv[1] == "UpdateAllImages": + update_all_images() +elif sys.argv[1] == "ReplaceREADMEHeader": + replace_readme_header() +elif sys.argv[1] == "UpdateC4WithNextBeta": + update_c4_next_beta_version() +else: + sys.stderr.write(f"{sys.argv[1]} is an unsupported transformation\n") + sys.exit(1)