From b713281324f34f8c38cafed6bf6678f7a1ebdbd8 Mon Sep 17 00:00:00 2001 From: Nate McCurdy Date: Wed, 19 Apr 2023 14:50:56 -0700 Subject: [PATCH] Clarify module release documentation --- _docs/releasing_version.md | 97 +++++++++++++++++++++++++------------- 1 file changed, 64 insertions(+), 33 deletions(-) diff --git a/_docs/releasing_version.md b/_docs/releasing_version.md index f221402..9f59144 100644 --- a/_docs/releasing_version.md +++ b/_docs/releasing_version.md @@ -6,69 +6,100 @@ summary: How to perform a complete version release, including modulesync and pub --- Creating a release is a two step process: -1. Prepare the release — setup everything so that peer review can happen and when everything is ready… +1. Prepare the release 2. Do the actual release ## Preparing a release -Run modulesync to ensure the dotfiles are up-to-date. +Before preparing a release, it may help to run modulesync to ensure the +dotfiles are up-to-date. If modulesync has been run recently by someone else, +you may not have to do it. See https://github.com/voxpupuli/modulesync for more +info on using modulesync. -Create a 'release pr'. This pull request updates the changelog and bumps the -version number to the target version, removing all release candidate -identifiers, i.e. from `0.10.7-rc0` to `0.10.7`. Here's an example: -[puppet-extlib's 0.10.7 release](https://github.com/voxpupuli/puppet-extlib/pull/43). -In most cases it is sufficient to update metadata.json. We try -to respect [semantic versioning](http://semver.org/) and decided that dropping ruby1.8 -support is a major change and requires a major version bump for the module. -(Only the minor version should be bumped if the module is pre version 1.0 and -ruby 1.8 support has been dropped.) - -If necessary, run `bundle install` before continuing. If you want you can also only install the needed gems: +### 1. Create a new branch for a "release pull request" +For example, if you want to release version `1.2.3` of a module: ```bash -bundle install --path .vendor/ --without system_tests development +git checkout -b "release_123" ``` -And in case you installed the gems before: +### 2. Bump the version + +Bump the version number in the module's `metadata.json`. + +The version bump must remove all release candidate identifiers and move to the +next appropriate release version. For example: `0.10.7-rc0` to `0.10.7`. + +Here's a Pull Request to use as a reference: +[puppet-extlib's 0.10.7 release](https://github.com/voxpupuli/puppet-extlib/pull/43). + +Please follow [semantic versioning](http://semver.org/) when changing the +version number. + +### 3. Update the CHANGELOG + +After bumping the version in `metadata.json`, use the following rake task to +automatically update the CHANGELOG. + +NOTE: This requires a [GitHub access token (docs on how to create +one)](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). +The changelog generator expects the token in the environment variable +`CHANGELOG_GITHUB_TOKEN` + +> If necessary, run `bundle install` before continuing. +> ```bash +> bundle install --path .vendor/ --without system_tests development +> ``` +> +> And in case you installed the gems before: +> ```bash +> bundle install --path .vendor/ --without system_tests development; bundle update; bundle clean +> ``` ```bash -bundle install --path .vendor/ --without system_tests development; bundle update; bundle clean +CHANGELOG_GITHUB_TOKEN='mytoken' bundle exec rake changelog ``` +The changelog generator checks for certain labels on closed issues and PRs +since the last release and groups them together. If the changes were neither +backwards-incompatible nor only bug fixes, make a minor release. Check the +generated diff for the CHANGELOG.md. If your chosen release version doesn't +match the generated changelog, update metadata.json and run the changelog task +again. + +### 4. Update Puppet Strings docs (if necessary) + If the module contains a Puppet Strings generated documentation, please ensure the file is up-to-date. A good indicator for a Puppet Strings -documentation is the existence of a REFERENCE.md file. You can automatically -generate the documentation by running the following rake task: +documentation is the existence of a `REFERENCE.md` file. + +Run the following rake task to update `REFERENCE.md`: ```bash bundle exec rake strings:generate:reference ``` -We can generate the changelog after updating the metadata.json with a rake task -(in most cases, this requires a -[GitHub access token (docs on how to create one)](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line): -the changelog generator expects the token in the environment variable `CHANGELOG_GITHUB_TOKEN`) - -```bash -CHANGELOG_GITHUB_TOKEN='mytoken' bundle exec rake changelog -``` +### 5. Create the Release Pull Request -The changelog generator checks for certain labels on closed issues and PRs since -the last release and groups them together. If the changes were neither -backwards-incompatible nor only bug fixes, make a minor release. Check the -generated diff for the CHANGELOG.md. If your chosen release version doesn't -match the generated changelog, update metadata.json and run the changelog task again. +Push your branch up to the module's repo or to a fork of the repo then create +the Pull Request. -Get community feedback on the release pr, label it with `skip-changelog`, get it merged. +Once created, get community feedback on the PR in Slack or IRC, label it with +`skip-changelog`, and then get it merged after approval. ## Doing the release -Checkout an updated copy of master +After your Pull Request from above gets merged, the next step is to do the +release. + +### 1. Checkout an updated copy of master ```bash git checkout master; git fetch origin; git pull origin master ``` +### 2. Run the 'release' rake task + Run the rake target `release`. This will: * create a new tag using the current version