1Releasing Ambassador
2====================
3
4If you just want to **use** Ambassador, check out https://www.getambassador.io/! You don't need to build - much less release! - anything, and in fact you shouldn't.
5
6If you don't work at Datawire, this document is probably not going to help you. Maybe check out [the developer guide](BUILDING.md) instead.
7
8----
9
10If you're still reading, you must be at Datawire. Congrats, you picked a fine place to work! To release Ambassador, you'll need credentials for our Github repos.
11
12Note. PRs will pile up on `master`. **Don't accept PRs for which CI doesn't show passing tests.**
13When we get to the stage of creating a release, all the PRs that we want to merge will have been merged
14and the CI will be green.
15
161. Once `master` has all the release drivers, tag `master` with an RC tag, e.g. `v0.77.0-rc.1`. **This version tag must start with a 'v'.** For example:
17 git tag v0.77.0-rc.1 master
18 git push --tags origin master
19
202. The RC tag will trigger CI to run a new build and new tests. It had better pass: if not, figure out why. Monitor https://travis-ci.com/datawire/amabassador/ until the CI for ambassador completes and is green.
21
223. The RC build will be available as e.g. `docker.io/datawire/ambassador:0.77.0-rc.1`. Any other testing you want to do against this image, rock on.
23
244. When you're happy that the RC is ready for GA, **first** assemble the list of changes that you'll put into CHANGELOG.md: (Note: place this list in a separate file, maybe `~/temp-list.txt`, but definitely not in CHANGELOG.md at this time.
25 - We always call out things contributed by the community, including who committed it
26 - you can mention the contributor with a link back to their GitHub page
27 - We always call out features and major bugfixes
28 - We always include links to GitHub issues where we can
29 - We rarely include fixes to the tests, build infrastructure, etc.
30 - Look at e.g. `git log v0.77.0..HEAD --no-merges --pretty '%h (%ai, %ae, %an): %s' -- ':(exclude)docs'`
31 and at the list of closed PRs. This is an awkward area of the release process as there are a log commits
32 and PRs but we only want to include a curated subset that makes sense to the users.
33
345. Once the change list is assembled, hand it to Marketing so they can either write a blog post or tell you it's not needed.
35
366. While the blog post is being written, switch to a new branch for the release.
37 - `git checkout -b rel/0.84.0` (or whatever version). **Do not name this branch "release/...".**
38
397. Use `make release-prep` to update `CHANGELOG.md`.
40 - This will prompt you for the release notes, so retrieve them from your previous file (maybe `~/temp-list.txt`).
41 The release notes are pasted in at a prompt (during the make), not read from a file, so you will need them
42 accessible to select-and-copy (suggestion: open your previous file in another window).
43 - It will _commit_, but not _push_, the updated files. Make sure the diffs it shows you look correct!
44 - Do a manual `git push` on your branch.
45
468. Now for the time-critical bit.
47 - Tag your branch with a GA tag like `v0.77.0` and let CI do its thing. **This version tag must start with a 'v'.**
48 - CI will retag the latest RC image as the GA image.
49
509. _After the CI run finishes_:
51 - Submit, and land, a PR for your branch.
52 - Go to https://github.com/datawire/ambassador/releases and create a new release.
53 - `make release-prep` should've output the text to paste into the release description.
54
55 **Note** that there must be at least one RC build before a GA, since the GA tag **does not** rebuild the docker images -- it retags the ones built by the RC build. This is intentional, to allow for testing to happen on the actual artifacts that will be released.
56
57 **Note also** that even though the version _tag_ starts with a 'v', the version _number_ displayed by the diag UI will _not_ start with a 'v'.**
58
5910. Submit a PR into the `helm/charts` repo to update things in `stable/ambassador`:
60 - in `Chart.yaml`, update `appVersion` with the new Ambassador version, and bump `version`.
61 - in `README.md`, update the default value of `image.tag`.
62 - in `values.yaml`, update `tag`.
63 - Helpful stuff for this:
64 - git checkout master # switch to master
65 - git fetch --all --prune # make sure our view of remotes is up to date
66 - git pull # pull down any changes to master
67 - git rebase upstream/master # move master on top of upstream
68 - git push # push rebases to our fork
69 - git checkout -b update/$VERSION # switch to a feature branch
70 - make your edits
71 - git commit -a # commit changes -- don't forget DCO in the message!
72 - git push origin update/$VERSION # push to feature branch
73 - open a PR
74 - Once your PR is merged, _delete the feature branch without merging it back to origin/master_.
75
7611. Update the getambassador.io website by submitting a PR to the `datawire/getambassador.io` repo.
77 - `src/releaseInfo.js` is the only file you should need to touch:
78 - `ReleaseType` comes from Marketing, usually "Feature Release", "Maintenance Release", or "Security Update"
79 - `CurrentVersion` is e.g. "0.78.0" -- no leading 'v' here
80 - `BlogLink` is the full URL of the blog post (from Marketing), or "" if there is no blog post
81 - Make your edits, submit a PR, get it merged. Done.
82 - If you want to test before submitting, use `yarn install && yarn start` and point a web browser to `localhost:8000`
83
84 Submit a PR to the Ambassador website repository to update the version on the homepage. Details can be found there on specifically how to do that.
View as plain text