Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify module release documentation #288

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Clarify module release documentation #288

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 64 additions & 33 deletions _docs/releasing_version.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do you think this is fine or should we enhance it with a sentence so people can check if it's actually up2date? each of our modules has the .msync.yml file with the version:

$ cat .msync.yml
---
# Managed by modulesync - DO NOT EDIT
# https://voxpupuli.org/docs/updating-files-managed-with-modulesync/

modulesync_config_version: '5.5.0'

Which maps to the tag at: https://github.com/voxpupuli/modulesync_config/tags

also maybe it's better to link to https://github.com/voxpupuli/modulesync_config/ and not https://github.com/voxpupuli/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
> ```
Comment on lines +49 to +57
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if this should be simplified to just always doing the install/update/clean command, so that you don't have to know the answer to when it would be necessary to run bundle install before continuing.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's the reason why I initially provided it as a long line. just copy paste it and it will set everything up.


```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
Expand Down