Skip to content
This repository was archived by the owner on Oct 3, 2023. It is now read-only.

Commit 9c75164

Browse files
songy23songy23
authored
Add releasing instructions in RELEASING.md. (#106)
* Add releasing instructions in RELEASING.md. * Re-organize the sections.
1 parent f303ae3 commit 9c75164

File tree

1 file changed

+187
-0
lines changed

1 file changed

+187
-0
lines changed

‎RELEASING.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# How to Create a Release of OpenCensus Proto (for Maintainers Only)
2+
3+
## Build Environments
4+
5+
We re-generate gen-go files and deploy jars to Maven Central under the following systems:
6+
7+
- Ubuntu 14.04
8+
9+
Other systems may also work, but we haven't verified them.
10+
11+
## Release Go files
12+
13+
To generate the Go files from protos, you'll need to install protoc and protoc-gen-go plugin first.
14+
Follow the instructions [here](http://google.github.io/proto-lens/installing-protoc.html) and
15+
[here](https://github.com/golang/protobuf#installation).
16+
17+
Then run the following commands to re-generate the gen-go files:
18+
19+
```bash
20+
$ git checkout -b update-gen-go
21+
$ cd src
22+
$ ./mkgogen.sh
23+
$ git commit -a -m "Update gen-go files."
24+
```
25+
26+
Go through PR review and merge the changes to GitHub.
27+
28+
## Tagging the Release
29+
30+
Our release branches follow the naming convention of `v<major>.<minor>.x`, while the tags include the
31+
patch version `v<major>.<minor>.<patch>`. For example, the same branch `v0.4.x` would be used to create
32+
all `v0.4` tags (e.g. `v0.4.0`, `v0.4.1`).
33+
34+
In this section upstream repository refers to the main opencensus-proto github
35+
repository.
36+
37+
Before any push to the upstream repository you need to create a [personal access
38+
token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).
39+
40+
1. Create the release branch and push it to GitHub:
41+
42+
```bash
43+
$ MAJOR=0 MINOR=4 PATCH=0 # Set appropriately for new release
44+
$ VERSION_FILES=(
45+
build.gradle
46+
pom.xml
47+
)
48+
$ git checkout -b v$MAJOR.$MINOR.x master
49+
$ git push upstream v$MAJOR.$MINOR.x
50+
```
51+
52+
2. Enable branch protection for the new branch, if you have admin access.
53+
Otherwise, let someone with admin access know that there is a new release
54+
branch.
55+
56+
- Open the branch protection settings for the new branch, by following
57+
[Github's instructions](https://help.github.com/articles/configuring-protected-branches/).
58+
- Copy the settings from a previous branch, i.e., check
59+
- `Protect this branch`
60+
- `Require pull request reviews before merging`
61+
- `Require status checks to pass before merging`
62+
- `Include administrators`
63+
64+
Enable the following required status checks:
65+
- `cla/google`
66+
- `continuous-integration/travis-ci`
67+
- Uncheck everything else.
68+
- Click "Save changes".
69+
70+
3. For `master` branch:
71+
72+
- Change root build files to the next minor snapshot (e.g.
73+
`0.5.0-SNAPSHOT`).
74+
75+
```bash
76+
$ git checkout -b bump-version master
77+
# Change version to next minor (and keep -SNAPSHOT)
78+
$ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$((MINOR+1)).0'\1/' \
79+
"${VERSION_FILES[@]}"
80+
$ ./gradlew build
81+
$ git commit -a -m "Start $MAJOR.$((MINOR+1)).0 development cycle"
82+
```
83+
84+
- Go through PR review and push the master branch to GitHub:
85+
86+
```bash
87+
$ git checkout master
88+
$ git merge --ff-only bump-version
89+
$ git push upstream master
90+
```
91+
92+
4. For `vMajor.Minor.x` branch:
93+
94+
- Change root build files to remove "-SNAPSHOT" for the next release
95+
version (e.g. `0.4.0`). Commit the result and make a tag:
96+
97+
```bash
98+
$ git checkout -b release v$MAJOR.$MINOR.x
99+
# Change version to remove -SNAPSHOT
100+
$ sed -i 's/-SNAPSHOT\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/\1/' "${VERSION_FILES[@]}"
101+
$ ./gradlew build
102+
$ git commit -a -m "Bump version to $MAJOR.$MINOR.$PATCH"
103+
$ git tag -a v$MAJOR.$MINOR.$PATCH -m "Version $MAJOR.$MINOR.$PATCH"
104+
```
105+
106+
- Change root build files to the next snapshot version (e.g.
107+
`0.4.1-SNAPSHOT`). Commit the result:
108+
109+
```bash
110+
# Change version to next patch and add -SNAPSHOT
111+
$ sed -i 's/[0-9]\+\.[0-9]\+\.[0-9]\+\(.*CURRENT_OPENCENSUS_PROTO_VERSION\)/'$MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT'\1/' \
112+
"${VERSION_FILES[@]}"
113+
$ ./gradlew build
114+
$ git commit -a -m "Bump version to $MAJOR.$MINOR.$((PATCH+1))-SNAPSHOT"
115+
```
116+
117+
- Go through PR review and push the release tag and updated release branch
118+
to GitHub:
119+
120+
```bash
121+
$ git checkout v$MAJOR.$MINOR.x
122+
$ git merge --ff-only release
123+
$ git push upstream v$MAJOR.$MINOR.$PATCH
124+
$ git push upstream v$MAJOR.$MINOR.x
125+
```
126+
127+
## Release Java Jar
128+
129+
Deployment to Maven Central (or the snapshot repo) is for all of the artifacts
130+
from the project.
131+
132+
### Prerequisites
133+
134+
If you haven't done already, please follow the instructions
135+
[here](https://github.com/census-instrumentation/opencensus-java/blob/master/RELEASING.md#prerequisites)
136+
to set up the OSSRH (OSS Repository Hosting) account and signing keys. This is required for releasing
137+
to Maven Central.
138+
139+
### Branch
140+
141+
Before building/deploying, be sure to switch to the appropriate tag. The tag
142+
must reference a commit that has been pushed to the main repository, i.e., has
143+
gone through code review. For the current release use:
144+
145+
```bash
146+
$ git checkout -b v$MAJOR.$MINOR.$PATCH tags/v$MAJOR.$MINOR.$PATCH
147+
```
148+
149+
### Initial Deployment
150+
151+
The following command will build the whole project and upload it to Maven
152+
Central. Parallel building [is not safe during
153+
uploadArchives](https://issues.gradle.org/browse/GRADLE-3420).
154+
155+
```bash
156+
$ ./gradlew clean build && ./gradlew -Dorg.gradle.parallel=false uploadArchives
157+
```
158+
159+
If the version has the `-SNAPSHOT` suffix, the artifacts will automatically go
160+
to the snapshot repository. Otherwise it's a release deployment and the
161+
artifacts will go to a staging repository.
162+
163+
When deploying a Release, the deployment will create [a new staging
164+
repository](https://oss.sonatype.org/#stagingRepositories). You'll need to look
165+
up the ID in the OSSRH UI (usually in the form of `opencensus-*`).
166+
167+
### Releasing on Maven Central
168+
169+
Once all of the artifacts have been pushed to the staging repository, the
170+
repository must first be `closed`, which will trigger several sanity checks on
171+
the repository. If this completes successfully, the repository can then be
172+
`released`, which will begin the process of pushing the new artifacts to Maven
173+
Central (the staging repository will be destroyed in the process). You can see
174+
the complete process for releasing to Maven Central on the [OSSRH
175+
site](http://central.sonatype.org/pages/releasing-the-deployment.html).
176+
177+
## Announcement
178+
179+
Once deployment is done, go to Github [release
180+
page](https://github.com/census-instrumentation/opencensus-proto/releases), press
181+
`Draft a new release` to write release notes about the new release.
182+
183+
You can use `git log upstream/v$MAJOR.$((MINOR-1)).x..upstream/v$MAJOR.$MINOR.x --graph --first-parent`
184+
or the Github [compare tool](https://github.com/census-instrumentation/opencensus-proto/compare/)
185+
to view a summary of all commits since last release as a reference.
186+
187+
Please pick major or important user-visible changes only.

0 commit comments

Comments
 (0)