diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 1b9b42fc..ce399b6e 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -246,46 +246,75 @@ This section is written primarily for maintainers, so we don't forget how to ini Take a look at our [releases page](https://github.com/gomods/athens/releases). This is how we release official new builds of Athens. Almost all of the release process is automatic. +## Notes about the release number + +Before we continue, please be sure you're familiar with our release numbering scheme. + +We follow the [semver](https://semver.org) convention for our release numbers. At the moment, we're not at `v1`, so release versions are `v0.x.y`. `x` is the `MINOR` number, and `y` is the `PATCH` number. You'll need to decide which one to update. + +If there are significant new features in this release, choose to update `x` and set `y` to 0. If there are just bugfixes, just increment the `y` version number. + ## Code freeze The first step to a release is a code freeze. This is 1-2 weeks (depending on the features and bugfixes we intend to release) during which we don't merge anything but critical bugfixes to the `master` branch. The code in `master` is essentially a release candidate (we don't cut a new branch for RC's at the moment) to test. +>If you are doing a patch release, you do not need to do a code freeze. + ## Release branch -Right before we un-freeze the `master` branch, we will cut a new branch called `release-v0.x.y`. Make sure the branch name starts with `release-v`, followed by the [semver](https://semver.org) release number. +You'll be creating a new branch that represents the code that will be released. It always looks like `release-v0.x.y`. The `v0.x.y` represents the semver version number. ->You need to have permissions to create a new branch in origin, whether through the GitHub site or running `push origin release-v0.x.x` +>Reminder, the `x` and `y` make up the semver number. `x` is the `MINOR` and `y` is the `PATCH` -### Note about the release number +You'll need to have permissions to create a new branch in origin, whether through the GitHub site or running `push origin release-v0.x.x`. -We follow the [semver](https://semver.org) convention for our release numbers. At the moment, we're not at `v1`, so release versions are `v0.x.y`. `x` is the `MINOR` number, and `y` is the `PATCH` number. You'll need to decide which one to update. +### Minor releases -If there are significant new features in this release, choose to update the minor version. Otherwise, choose to update the patch version. Reminder: semver convention looks like this: `v0.MINOR.PATCH`. +If you're doing a minor release, you'll be incrementing `x` and setting `y` to 0 in the branch name. For example, if the previous release was `v0.1.2`, the previous release branch will be `release-v0.1.2`. Your new version will be `v0.2.0` and new release branch will be `release-v0.2.0`. + +Cut minor release branches from the `master` branch. + +### Patch releases + +If you're doing a patch release, you'll be incrementing only the `y` version number. In this case, the new version will be `v0.2.1` and new branch will be `release-v0.2.1`. + +Cut patch release branches from the most recent release branch. Since these branches will only fix bugs, you'll need to find the commits from `master` that have the fixes in them and cherry pick them into the new patch release branch. For example: + +```console +$ git checkout -b release-v0.2.1 upstream/release-v0.2.0 +$ git cherry-pick +.... +``` + +### Updating the helm chart + +Regardless of which branch you created, you'll need to update the helm chart number. After you've cut the branch, make sure to change the versions in the [`Chart.yaml`](https://github.com/gomods/athens/blob/master/charts/athens-proxy/Chart.yaml) file: + +- Increment the patch number in the [`version` field](https://github.com/gomods/athens/blob/master/charts/athens-proxy/Chart.yaml#L2) +- Set the [`appVersion` field](https://github.com/gomods/athens/blob/master/charts/athens-proxy/Chart.yaml#L2) to the semver of the new branch. Do not include the `v` prefix ## Creating the new release in GitHub Go to the [create new release page](https://github.com/gomods/athens/releases/new) and draft a new release. See below for what data to put into the fields you see: -- **Tag version** - This should be the same `v0.x.y` number you put into the release branch. Again, make sure this tag starts with `v` +- **Tag version** - This should be the same `v0.x.y` number you put into the release branch. Make sure this tag starts with `v` and that the tag target is the proper release branch. - **Release Title** - Make sure the title is prefixed by the release number including the `v`. If you want to write something creative in the rest of the title, go for it! -- **Describe this release** - Make sure to write what features this release includes, and any notable bugfixes. Also, thank all the folks who contributed to the release. You can find that information in a link that looks like this: `https://github.com/gomods/athens/compare/master...v0.7.2`. Substitute the `v0.7.2` from the most recent release before the one you are creating +- **Describe this release** - Make sure to write what features this release includes, and any notable bugfixes. Also, thank all the folks who contributed to the release. You can find that information in a link that looks like this: `https://github.com/gomods/athens/compare/$PREVIOUS_TAG...$CURRENT_TAG`. Substitute `$PREVIOUS_TAG` for the last semver and `$CURRENT_TAG` to this one. When you're done, press the "Publish Release" button. After you do, our [Drone](https://cloud.drone.io) job will do almost everything. -Make sure the Drone job finished, and check in Docker Hub to make sure the new release showed up in the [tags](https://hub.docker.com/r/gomods/athens/tags) section. +Make sure the Drone CI/CD job finished, and check in Docker Hub to make sure the new release showed up in the [tags](https://hub.docker.com/r/gomods/athens/tags) section. ## Finishing up The Drone job will do everything except: - Tweet out about the new release -- Update the helm chart +- Update the helm chart in the `master` branch If you are a core maintainer and don't have access to the `@gomods` account, ask one of the maintainers to give you access. [Here](https://twitter.com/gomodsio/status/1240016379962691585) is an example showing the general format of these tweets. Obviously you should use your creativity here though! -Finally, you'll need to create two identical PRs to update the Helm chart. Create one to merge into the `master` branch, and another to merge into the `release-v0.x.y` branch you created. - -You'll need to update two files: +Finally, you'll need to update the helm version number in the `master` branch. Create a new branch called `update-helm-$CURRENT_TAG` and update the following files: - [charts/athens-proxy/values.yaml](https://github.com/gomods/athens/blob/master/charts/athens-proxy/values.yaml) - update the `image.tag` field to the latest version number you created, including the `v`. This field should be near the top of the file - [charts/athens-proxy/Chart.yaml](https://github.com/gomods/athens/blob/master/charts/athens-proxy/Chart.yaml) - update the `version` field and the `appVersion` field @@ -293,3 +322,5 @@ You'll need to update two files: - Change the `appVersion` field to the tag name of the GitHub version you created, including the `v` [Here](https://github.com/gomods/athens/pull/1574) is an example of how to do this. + +Finally, create a pull request from your new branch into the `master` branch. It will be reviewed and merged as soon as possible.