|
| 1 | +# Gophercloud release |
| 2 | + |
| 3 | +## Contributions |
| 4 | + |
| 5 | +### The semver label |
| 6 | + |
| 7 | +Gophercloud follows [semver](https://semver.org/). |
| 8 | + |
| 9 | +Each Pull request must have a label indicating its impact on the API: |
| 10 | +* `semver:patch` for changes that don't impact the API |
| 11 | +* `semver:minor` for changes that impact the API in a backwards-compatible fashion |
| 12 | +* `semver:major` for changes that introduce a breaking change in the API |
| 13 | + |
| 14 | +Automation prevents merges if the label is not present. |
| 15 | + |
| 16 | +### Metadata |
| 17 | + |
| 18 | +The release notes for a given release are generated based on the PR title and its milestone: |
| 19 | +* make sure that the PR title is descriptive |
| 20 | +* add a milestone based on the semver label: x++ if major, y++ if minor, z++ if patch. |
| 21 | + |
| 22 | +## Release of a new version |
| 23 | + |
| 24 | +### Step 1: Check the metadata |
| 25 | + |
| 26 | +Check that all pull requests merged since the last release have the right milestone. |
| 27 | + |
| 28 | +### Step 2: Release notes and version string |
| 29 | + |
| 30 | +Once all PRs have a sensible title and are added to the right milestone, generate the release notes with the [`gh`](https://github.com/cli/cli) tool: |
| 31 | +```shell |
| 32 | +gh pr list \ |
| 33 | + --state merged \ |
| 34 | + --search 'milestone:vx.y.z' \ |
| 35 | + --json number,title \ |
| 36 | + --template \ |
| 37 | + '{{range .}}* {{ printf "[GH-%v](https://github.com/gophercloud/gophercloud/pull/%v)" .number .number }} {{ .title }} |
| 38 | +{{end}}' |
| 39 | +``` |
| 40 | + |
| 41 | +Replace `x.y.z` with the current milestone. |
| 42 | + |
| 43 | +Add that to the top of `CHANGELOG.md`. Also add any information that could be useful to consumers willing to upgrade. |
| 44 | + |
| 45 | +**Set the new version string in the `DefaultUserAgent` constant in `provider_client.go`.** |
| 46 | + |
| 47 | +Create a PR with these two changes. The new PR should be labeled with the semver label corresponding to the type of bump, and the milestone corresponding to its version. |
| 48 | + |
| 49 | +### Step 3: Git tag and Github release |
| 50 | + |
| 51 | +The Go mod system relies on Git tags. In order to simulate a review mechanism, we rely on Github to create the tag through the Release mechanism. |
| 52 | + |
| 53 | +* [Prepare a new release](https://github.com/gophercloud/gophercloud/releases/new) |
| 54 | +* Let Github generate the release notes by clicking on Generate release notes |
| 55 | +* Click on **Save draft** |
| 56 | +* Ask another Gophercloud maintainer to review and publish the release |
| 57 | + |
| 58 | +_Note: never change a release or force-push a tag. Tags are almost immediately picked up by the Go proxy and changing the commit it points to will be detected as tampering._ |
0 commit comments