Skip to content

Add DEVELOPING.md to document release. #428

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

Merged
merged 3 commits into from
Mar 30, 2021
Merged

Add DEVELOPING.md to document release. #428

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f87a049
add DEVELOPING.md to document release. Addresses https://github.com/b…
Mar 4, 2021
1211d74
Merge branch 'master' into jonathon--add-DEVELOPING-dot-md-mar2021
Mar 4, 2021
c1b979b
Merge branch 'master' into jonathon--add-DEVELOPING-dot-md-mar2021
Mar 30, 2021
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
36 changes: 36 additions & 0 deletions DEVELOPING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# For Developers

## Releasing

Start from a clean checkout at `master`.

Before running through the release it's good to run the build and the tests locally, and make sure CI is passing. You can
also test-drive the commit in an existing Bazel workspace to sanity check functionality.

#### Determining Semantic Version

**rules_python** is currently using [Zero-based versioning](https://0ver.org/) and thus backwards-incompatible API
changes still come under the minor-version digit. So releases with API changes and new features bump the minor, and
those with only bug fixes and other minor changes bump the patch digit.

#### Steps

1. Update `version.bzl` with the new semantic version `X.Y.Z`.
2. Run `bazel build //distro:rules_python-X.Y.Z` to build the distributed tarball.
3. Calculate the Sha256 hash of the tarball. This hash will be used in the `http_archive` rules that download the new release.
1. Example command for OSX: `shasum --algorithm 256 bazel-bin/distro/rules_python-0.1.0.tar.gz`
Copy link
Contributor

Choose a reason for hiding this comment

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

Slightly confusing that we generate a sha sum for the release and then embed it in the release commit. Shouldn't adding the new sha change the release sha?

Copy link
Author

Choose a reason for hiding this comment

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

Yeah it is confusing I agree. It doesn't change the sha256 because the sha256 is added into the examples/ directory which isn't included in the sha'd distributable. It a bit awkward to do it this way but it allows you to have one commit "release X.Y.Z" that contains the necessary version.bzl bump and also updates to the examples (and README possibly).

It could be more straightforward though to just do the examples/ update in a followup commit.

Copy link
Contributor

Choose a reason for hiding this comment

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

nice --algorithm instead of -a

4. Update nested examples in `examples/*/WORKSPACE` to get the new semantic version with the new `sha256` hash.
5. Create commit called "Release X.Y.Z"
1. ["release 0.1.0"](https://github.com/bazelbuild/rules_python/commit/c8c79aae9aa1b61d199ad03d5fe06338febd0774) is an example commit.
6. Tag that commit as `X.Y.Z`. Eg. `git tag X.Y.Z`
7. Push the commit and the new tag to `master`.
8. Run `bazel build //distro:relnotes` from within workspace and then from repo root run `cat bazel-bin/distro/relnotes.txt` to get the 'install instructions' that are added as release notes.
1. Check the `sha256` value matches the one you calculated earlier.
9. ["Draft a new release"](https://github.com/bazelbuild/rules_python/releases/new) in Github (manual for now), selecting the recently pushed `X.Y.Z` tag.
Upload the release artifact from `rules_python-[version].tar.gz`. Also copy the `relnotes.txt` from step 8, adding anything extra if desired.

#### After release creation in Github

1. Update `README.md` to point at new release.
2. Ping @philwo to get the new release added to mirror.bazel.build. See [this comment on issue #400](https://github.com/bazelbuild/rules_python/issues/400#issuecomment-779159530) for more context.
3. Announce the release in the #python channel in the Bazel slack (bazelbuild.slack.com).