From f4be554f608f12e9643d4cecd20f4d66c148ca4c Mon Sep 17 00:00:00 2001 From: Matthew Fernandez Date: Fri, 24 Sep 2021 17:20:05 -0700 Subject: [PATCH] adjust the release process to not require gen_version.py tweaks MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit This change has two primary motivations: 1. Streamlining the release steps and reducing the opportunities for human error; and 2. Improving clarity in the release artifacts. Following this change, no edits are required to gen_version.py in order to cut a new release. The Graphviz version – both inter-release and for releases themselves – is derived exclusively from CHANGELOG.md. The effect of this is expected to be: 1. Cleaner release commits. No more regular churn of gen_version.py. 2. More obvious CHANGELOG.md in the release artifacts. This file will no longer have a spurious “[Unreleased]” heading preceding the actual changelog for the release. --- CHANGELOG.md | 4 +-- DEVELOPERS.md | 55 +++++++++++++++++++++++++--------------- gen_version.py | 68 ++++++++++++++++++++++++++++++++++++++++++-------- 3 files changed, 94 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b26b56b9..a715d35a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [Unreleased (2.49.2)] ### Changed @@ -1543,7 +1543,7 @@ March 13, 2000: Use AM_PROG_LIBTOOL instead of AC_PROG_LIBTOOL in configure.in. John Ellson ``` -[Unreleased]: https://gitlab.com/graphviz/graphviz/compare/2.49.1...main +[Unreleased (2.49.2)]: https://gitlab.com/graphviz/graphviz/compare/2.49.1...main [2.49.1]: https://gitlab.com/graphviz/graphviz/compare/2.49.0...2.49.1 [2.49.0]: https://gitlab.com/graphviz/graphviz/compare/2.48.0...2.49.0 [2.48.0]: https://gitlab.com/graphviz/graphviz/compare/2.47.3...2.48.0 diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 62f9b4810..851d1be3d 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -52,6 +52,11 @@ This project adheres to Before making the release, it must be decided if it is a *major*, *minor* or *patch* release. +If you are making a change that will require an upcoming major or minor version +increment, update the planned version for the next release in parentheses after +the `Unreleased` heading in `CHANGELOG.md`. Remember to also update the diff +link for this heading at the bottom of `CHANGELOG.md`. + #### Stable release versions and development versions numbering convention See [`gen_version.py`](https://gitlab.com/graphviz/graphviz/-/blob/main/gen_version.py). @@ -73,30 +78,24 @@ is green Example: `stable-release-2.44.1` -1. Edit `gen_version.py` according to instructions in that file. - 1. Edit `CHANGELOG.md` - Add the new version between `[Unreleased]` and the previous - version. + Change the `[Unreleased (…)]` heading to the upcoming release version and + target release date. At the bottom of the file, add an entry for the new version. These entries are not visible in the rendered page, but are essential for the version links to the GitLab commit comparisons to work. - Example (from - [commit 5e0d3b1841b7e358274c916b52276d251eabef3d](https://gitlab.com/graphviz/graphviz/-/commit/5e0d3b1841b7e358274c916b52276d251eabef3d#ab09011fa121d0a2bb9fa4ca76094f2482b902b7)): + Example: ```diff - ## [Unreleased] - + -## [Unreleased (2.44.1)] +## [2.44.1] - 2020-06-29 - + ``` ```diff - -[Unreleased]: https://gitlab.com/graphviz/graphviz/compare/2.44.0...main - +[Unreleased]: https://gitlab.com/graphviz/graphviz/compare/2.44.1...main + -[Unreleased (2.44.1)]: https://gitlab.com/graphviz/graphviz/compare/2.44.0...main +[2.44.1]: https://gitlab.com/graphviz/graphviz/compare/2.44.0...2.44.1 [2.44.0]: https://gitlab.com/graphviz/graphviz/compare/2.42.4...2.44.0 [2.42.4]: https://gitlab.com/graphviz/graphviz/compare/2.42.3...2.42.4 @@ -125,18 +124,34 @@ is green 1. The “deployment” CI task will automatically create a release on the [Gitlab releases tab](https://gitlab.com/graphviz/graphviz/-/releases). If a - release is not created, check that your modifications to `gen_version.py` - correctly set a version conforming to the regular expression `\d+\.\d+\.\d+`. - The “deployment” CI task will also create a Git tag for the version, e.g. - `2.44.1`. + release is not created, double check your steps and/or inspect + `gen_version.py` to ensure it is operating correctly. The “deployment” CI + task will also create a Git tag for the version, e.g. `2.44.1`. #### Returning to the development series 1. Create a new local branch and name it e.g. `return-to--dev` - Example: `return-to-2.45-dev` + Example: `return-to-2.44-dev` + +1. Add a new `[Unreleased (…)]` heading to `CHANGELOG.md`. At the bottom of + the file, add a new entry for the next release. + + Example: + + ```diff + +## [Unreleased (2.44.2)] + + + ## [2.44.1] - 2020-06-29 + ``` -1. Edit `gen_version.py` again according to instructions in that file. + ```diff + +[Unreleased (2.44.2)]: https://gitlab.com/graphviz/graphviz/compare/2.44.1...main + [2.44.1]: https://gitlab.com/graphviz/graphviz/compare/2.44.0...2.44.1 + [2.44.0]: https://gitlab.com/graphviz/graphviz/compare/2.42.4...2.44.0 + [2.42.4]: https://gitlab.com/graphviz/graphviz/compare/2.42.3...2.42.4 + [2.42.3]: https://gitlab.com/graphviz/graphviz/compare/2.42.2...2.42.3 + ``` 1. Commit: @@ -144,15 +159,15 @@ is green If patch version was incremented: - Example: `git commit -m "Move back to 2.45 development series"` + Example: `git commit -m "Move back to 2.44 development series"` else (if major or minor version was incremented): - Example: `git commit -m "Start 2.47 development series"` + Example: `git commit -m "Start 2.45 development series"` 1. Push: - Example: `git push origin return-to-2.45-dev` + Example: `git push origin return-to-2.44-dev` 1. Wait until the pipeline has run for your new branch and check that it's green diff --git a/gen_version.py b/gen_version.py index 60caeb000..a10924f1a 100644 --- a/gen_version.py +++ b/gen_version.py @@ -24,12 +24,62 @@ Entry version Entry collection Output import argparse from datetime import datetime import os +from pathlib import Path +import re import subprocess import sys +from typing import Tuple + +CHANGELOG = Path(__file__).parent / "CHANGELOG.md" +assert CHANGELOG.exists(), "CHANGELOG.md file missing" + +def get_version() -> Tuple[int, int, int, str]: + """ + Derive a Graphviz version from the changelog information. + + Returns a tuple of major version, minor version, patch version, + "stable"/"development". + """ + + # is this a development revision (as opposed to a stable release)? + is_development = False + + with open(CHANGELOG, encoding="utf-8") as f: + for line in f: + + # is this a version heading? + m = re.match(r"## \[(?P[^\]]*)\]", line) + if m is None: + continue + heading = m.group("heading") + + # is this the leading unreleased heading of a development version? + UNRELEASED_PREFIX = "Unreleased (" + if heading.startswith(UNRELEASED_PREFIX): + is_development = True + heading = heading[len(UNRELEASED_PREFIX):] + + # extract the version components + m = re.match(r"(?P\d+)\.(?P\d+)\.(?P\d+)", heading) + if m is None: + raise RuntimeError("non-version ## heading encountered before seeing a " + "version heading") + + major = int(m.group("major")) + minor = int(m.group("minor")) + patch = int(m.group("patch")) + break + + else: + # we read the whole changelog without finding a version + raise RuntimeError("no version found") + + if is_development: + coll = "development" + else: + coll = "stable" -collection = "development" - -version = "2.49.2" + return major, minor, patch, coll graphviz_date_format = "%Y%m%d.%H%M" iso_date_format = "%Y-%m-%d %H:%M:%S" @@ -76,16 +126,12 @@ args = parser.parse_args() date_format = args.date_format or graphviz_date_format -assert collection in ("stable", "development"), \ - 'The collection is not "stable" or "development"' -assert len(version.split(".")) == 3, "Wrong number of version elements" -assert all(part.isnumeric() for part in version.split(".")), \ - "All version elements are not numeric" +major_version, minor_version, patch_version, collection = get_version() if collection == "development": - version += "~dev" - -major_version, minor_version, patch_version = version.split(".") + patch_version = f"{patch_version}~dev" +else: + patch_version = str(patch_version) if not patch_version.isnumeric() or args.date_format: os.environ["TZ"] = "UTC" -- 2.40.0