Add releasing instructions in RELEASING.md. (#106)
* Add releasing instructions in RELEASING.md. * Re-organize the sections.pull/107/head
Yang Song
6 years ago
committed by
GitHub
parent
f303ae3f8d
commit
9c751640ae
1 changed files with 187 additions and 0 deletions
@ -0,0 +1,187 @@ |
||||
# How to Create a Release of OpenCensus Proto (for Maintainers Only) |
||||
|
||||
## Build Environments |
||||
|
||||
We re-generate gen-go files and deploy jars to Maven Central under the following systems: |
||||
|
||||
- Ubuntu 14.04 |
||||
|
||||
Other systems may also work, but we haven't verified them. |
||||
|
||||
## Release Go files |
||||
|
||||
To generate the Go files from protos, you'll need to install protoc and protoc-gen-go plugin first. |
||||
Follow the instructions [here](http://google.github.io/proto-lens/installing-protoc.html) and |
||||
[here](https://github.com/golang/protobuf#installation). |
||||
|
||||
Then run the following commands to re-generate the gen-go files: |
||||
|
||||
```bash |
||||
$ git checkout -b update-gen-go |
||||
$ cd src |
||||
$ ./mkgogen.sh |
||||
$ git commit -a -m "Update gen-go files." |
||||
``` |
||||
|
||||
Go through PR review and merge the changes to GitHub. |
||||
|
||||
## Tagging the Release |
||||
|
||||
Our release branches follow the naming convention of `v<major>.<minor>.x`, while the tags include the |
||||
patch version `v<major>.<minor>.<patch>`. For example, the same branch `v0.4.x` would be used to create |
||||
all `v0.4` tags (e.g. `v0.4.0`, `v0.4.1`). |
||||
|
||||
In this section upstream repository refers to the main opencensus-proto github |
||||
repository. |
||||
|
||||
Before any push to the upstream repository you need to create a [personal access |
||||
token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). |
||||
|
||||
1. Create the release branch and push it to GitHub: |
||||
|
||||
```bash |
||||
$ MAJOR=0 MINOR=4 PATCH=0 # Set appropriately for new release |
||||
$ VERSION_FILES=( |
||||
build.gradle |
||||
pom.xml |
||||
) |
||||
$ git checkout -b v$MAJOR.$MINOR.x master |
||||
$ git push upstream v$MAJOR.$MINOR.x |
||||
``` |
||||
|
||||
2. Enable branch protection for the new branch, if you have admin access. |
||||
Otherwise, let someone with admin access know that there is a new release |
||||
branch. |
||||
|
||||
- Open the branch protection settings for the new branch, by following |
||||
[Github's instructions](https://help.github.com/articles/configuring-protected-branches/). |
||||
- Copy the settings from a previous branch, i.e., check |
||||
- `Protect this branch` |
||||
- `Require pull request reviews before merging` |
||||
- `Require status checks to pass before merging` |
||||
- `Include administrators` |
||||
|
||||
Enable the following required status checks: |
||||
- `cla/google` |
||||
- `continuous-integration/travis-ci` |
||||
- Uncheck everything else. |
||||
- Click "Save changes". |
||||
|
||||
3. For `master` branch: |
||||
|
||||
- Change root build files to the next minor snapshot (e.g. |
||||
`0.5.0-SNAPSHOT`). |
||||
|
||||
```bash |
||||
$ git checkout -b bump-version master |
||||
# Change version to next minor (and keep -SNAPSHOT) |
||||
$ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$((MINOR+1)).0'\1/' \ |
||||
"${VERSION_FILES[@]}" |
||||
$ ./gradlew build |
||||
$ git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle" |
||||
``` |
||||
|
||||
- Go through PR review and push the master branch to GitHub: |
||||
|
||||
```bash |
||||
$ git checkout master |
||||
$ git merge --ff-only bump-version |
||||
$ git push upstream master |
||||
``` |
||||
|
||||
4. For `vMajor.Minor.x` branch: |
||||
|
||||
- Change root build files to remove "-SNAPSHOT" for the next release |
||||
version (e.g. `0.4.0`). Commit the result and make a tag: |
||||
|
||||
```bash |
||||
$ git checkout -b release v$MAJOR.$MINOR.x |
||||
# Change version to remove -SNAPSHOT |
||||
$ sed -i 's/-SNAPSHOT\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/\1/' "${VERSION_FILES[@]}" |
||||
$ ./gradlew build |
||||
$ git commit -a -m "Bump version to $MAJOR.$MINOR.$PATCH" |
||||
$ git tag -a v$MAJOR.$MINOR.$PATCH -m "Version $MAJOR.$MINOR.$PATCH" |
||||
``` |
||||
|
||||
- Change root build files to the next snapshot version (e.g. |
||||
`0.4.1-SNAPSHOT`). Commit the result: |
||||
|
||||
```bash |
||||
# Change version to next patch and add -SNAPSHOT |
||||
$ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT'\1/' \ |
||||
"${VERSION_FILES[@]}" |
||||
$ ./gradlew build |
||||
$ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT" |
||||
``` |
||||
|
||||
- Go through PR review and push the release tag and updated release branch |
||||
to GitHub: |
||||
|
||||
```bash |
||||
$ git checkout v$MAJOR.$MINOR.x |
||||
$ git merge --ff-only release |
||||
$ git push upstream v$MAJOR.$MINOR.$PATCH |
||||
$ git push upstream v$MAJOR.$MINOR.x |
||||
``` |
||||
|
||||
## Release Java Jar |
||||
|
||||
Deployment to Maven Central (or the snapshot repo) is for all of the artifacts |
||||
from the project. |
||||
|
||||
### Prerequisites |
||||
|
||||
If you haven't done already, please follow the instructions |
||||
[here](https://github.com/census-instrumentation/opencensus-java/blob/master/RELEASING.md#prerequisites) |
||||
to set up the OSSRH (OSS Repository Hosting) account and signing keys. This is required for releasing |
||||
to Maven Central. |
||||
|
||||
### Branch |
||||
|
||||
Before building/deploying, be sure to switch to the appropriate tag. The tag |
||||
must reference a commit that has been pushed to the main repository, i.e., has |
||||
gone through code review. For the current release use: |
||||
|
||||
```bash |
||||
$ git checkout -b v$MAJOR.$MINOR.$PATCH tags/v$MAJOR.$MINOR.$PATCH |
||||
``` |
||||
|
||||
### Initial Deployment |
||||
|
||||
The following command will build the whole project and upload it to Maven |
||||
Central. Parallel building [is not safe during |
||||
uploadArchives](https://issues.gradle.org/browse/GRADLE-3420). |
||||
|
||||
```bash |
||||
$ ./gradlew clean build && ./gradlew -Dorg.gradle.parallel=false uploadArchives |
||||
``` |
||||
|
||||
If the version has the `-SNAPSHOT` suffix, the artifacts will automatically go |
||||
to the snapshot repository. Otherwise it's a release deployment and the |
||||
artifacts will go to a staging repository. |
||||
|
||||
When deploying a Release, the deployment will create [a new staging |
||||
repository](https://oss.sonatype.org/#stagingRepositories). You'll need to look |
||||
up the ID in the OSSRH UI (usually in the form of `opencensus-*`). |
||||
|
||||
### Releasing on Maven Central |
||||
|
||||
Once all of the artifacts have been pushed to the staging repository, the |
||||
repository must first be `closed`, which will trigger several sanity checks on |
||||
the repository. If this completes successfully, the repository can then be |
||||
`released`, which will begin the process of pushing the new artifacts to Maven |
||||
Central (the staging repository will be destroyed in the process). You can see |
||||
the complete process for releasing to Maven Central on the [OSSRH |
||||
site](http://central.sonatype.org/pages/releasing-the-deployment.html). |
||||
|
||||
## Announcement |
||||
|
||||
Once deployment is done, go to Github [release |
||||
page](https://github.com/census-instrumentation/opencensus-proto/releases), press |
||||
`Draft a new release` to write release notes about the new release. |
||||
|
||||
You can use `git log upstream/v$MAJOR.$((MINOR-1)).x..upstream/v$MAJOR.$MINOR.x --graph --first-parent` |
||||
or the Github [compare tool](https://github.com/census-instrumentation/opencensus-proto/compare/) |
||||
to view a summary of all commits since last release as a reference. |
||||
|
||||
Please pick major or important user-visible changes only. |
||||
Loading…
Reference in new issue