From: Magnus Jacobsson Date: Fri, 5 Jun 2020 11:59:02 +0000 (+0200) Subject: Add DEVELOPERS.md with release instructions X-Git-Tag: 2.44.1~11^2~1^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=e563b756c0fc3970822c29fa3f92ab56d04effc2;p=graphviz Add DEVELOPERS.md with release instructions --- diff --git a/DEVELOPERS.md b/DEVELOPERS.md new file mode 100644 index 000000000..9f193d05c --- /dev/null +++ b/DEVELOPERS.md @@ -0,0 +1,184 @@ +# Developer's Guide + +## Table of contents + +[[_TOC_]] + +## How to make a release + +### A note about the examples below + +The examples below are for the 2.44 release. Modify the version +number for the actual release. The example commits were cherry-picked +from different releases since mistakes were made during the 2.44 +release (and all other previous releases as well). + +### Using a fork or a clone of the original repo + +The instructions below assume that the actions are performed from a +fork and that the orignal repository has been added as a remote with: + +`git remote add graphviz https://gitlab.com/graphviz/graphviz.git` + +If the actions instead are performed from a clone of the orignal repo, +`git push graphviz` should be replaced with `git push origin`. + +### Deciding the release version number + +This project adheres to +[Semantic Versioning](https://semver.org/spec/v2.0.0.html). +Before making the release, it must be decided if it is a *major*, *minor* or +*patch* release. + +#### Stable release versions and development versions numbering convention + +Stable release versions always have an *even* minor version and +development versions always have an *odd* minor version that is the +latest stable release minor version *plus* 1. Development releases +have the patch version automatically set to the +[committer date](https://git-scm.com/docs/pretty-formats#Documentation/pretty-formats.txt-emciem) +(not the [author date](https://git-scm.com/docs/pretty-formats#Documentation/pretty-formats.txt-emadem) +which is what `git log` shows by default) of the latest commit using the format `%Y%m%d.%H%M`. + +Release version examples: + +- 2.42.3 +- 2.42.4 +- 2.44.0 + +Development version examples: + +- 2.43.20200403.0503 +- 2.45.20200601.1555 + +### Instructions + +1. Check that the +[master pipeline](https://gitlab.com/graphviz/graphviz/-/pipelines?ref=master) +is green + +1. Edit `autogen.sh`, `appveyor.yml` and `CMakeLists.txt`: + + Incement patch version with 1 *or* minor version to the next *even* number. + + Example: 466402bb70105dd74282cd9da6bbde9da02a9b3c + and 2cc6ed876212ec65fccd4a90028335b338d3ccc0 (for release 2.42.4). + +1. Edit `CHANGELOG.md` (provided that !1394 is merged) + + Add the new version between `[Unreleased]` and the previous + version. + + 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. + + Updating the `CHANGELOG.md` has never yet been done for the + Graphviz project, but [this + example](https://github.com/magjac/d3-graphviz/commit/59f515686a3fdb4da2a04d02665abfb2e583d898#diff-4ac32a78649ca5bdd8e0ba38b7006a1e) + shows how it's done for another project. + +1. Commit: + + `git add -p` + + `git commit -m "Stable Release 2.44.0"` + +1. Push: + + `git push graphviz master` + +1. Wait for the +[master pipeline](https://gitlab.com/graphviz/graphviz/-/pipelines?ref=master) +to run for the new commit and check that it succeeds + +1. Tag release: + + `git tag -a -m "Stable Release 2.44.0" stable_release_2.44.0` + +1. Push tag: + + `git push graphviz stable_release_2.44.0` + +1. Create a release at [GitHub releases](https://gitlab.com/graphviz/graphviz/-/releases) + + Create a new tag *without* the `stable_release_` prefix: `2.44.0` + +1. Edit `autogen.sh`, `appveyor.yml` and `CMakeLists.txt`. + + Update the release again for the next devevelopment series. If + minor release, increment minor version to the next odd number and + zero the patch version, *otherwise* increment the patch + version. See e.g. 28e09c876c4c01e979b5801c89f6f59855c8b4ca and + fa40209b378c8435fd1c8d6c74ff0ff95c9f45b2 + +1. Commit: + + `git add -p` + + If patch version was incremented: + + `git commit -m "Move back to 2.43 development series"` + + else (if major or minor version was incremented): + + `git commit -m "Start 2.45 development series"` + +1. Push: + + `git push graphviz master` + +1. Update the links to the release on the **Downloads** web page through +[Edit this page](https://gitlab.com/graphviz/graphviz.gitlab.io/-/edit/master/_pages/10_download.md): + - Visit the + [Appveyor history](https://ci.appveyor.com/project/ellson/graphviz-pl238/history) + and find the URL to the Windows release build. + - In the **Windows** section, for the **Stable 2.44 Windows install packages** link: + - Update the text with the new version number. + - Update the link with the new URL. + Example: [23bf8be297b9b4d11d345020acbe823f76bee267](https://gitlab.com/graphviz/graphviz.gitlab.io/-/commit/23bf8be297b9b4d11d345020acbe823f76bee267). + +1. Update the links to the released source code package files on the **Sources** web +page through +[Edit this page](https://gitlab.com/graphviz/graphviz.gitlab.io/-/edit/master/download/source/index.md): + - Visit the + [portable_source](https://www2.graphviz.org/Packages/stable/portable_source/) + directory + and find the URL's to the `tar.gz` and the `tar.gz.md5` files. + - In the **current stable release** column in the **graphviz** table: + - Update the text with the new version number. + - Update the links with the new URL's. + +### TODO (with these release instructions) + +- Update the example commits above after next release (provided that + we manage to get it right the first time) and remove the note about + it at the top and the reference to "another project". + +- Add an example commit for the **Sources** page after the next release. + +- Investigate if the tagging can be simplifed when making the next + release. The current approach using dual tags is based on that we + wanted to tag before push and then make a GitLab release. It didn't + seem possible to create a GitLab release for an existing tag, hence + to need to create another tag without the `stable_release_` prefix + (This seemed to be a good idea at the time but might have been the + wrong conclusion). + +## How to update this guide + +### Markdown flavor used + +This guide uses +[GitLab Flavored Markdown (GFM)](https://docs.gitlab.com/ce/user/markdown.html#gitlab-flavored-markdown-gfm]). + +### Rendering this guide locally + +This guide can be rendered locally with e.g. [Pandoc](https://pandoc.org/): + +`pandoc DEVELOPERS.md --from=gfm -t html -o DEVELOPERS.html` + +### Linting this guide locally + +[markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) +can be used to lint it.