diff --git a/.travis.yml b/.travis.yml index 150c552f9c..b1367cf2e0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,4 +1,4 @@ -dist: xenial +dist: bionic language: python python: - 3.6 @@ -81,3 +81,5 @@ jobs: ## ref: https://docs.travis-ci.com/user/environment-variables/#encrypting-environment-variables - secure: jpFpbMccpjGP+otWH2Z03VFdtR9AAu2vzrNxsoZ3IvJvrO4MfzYJ3uSCDQuB0NG9gBgaAscpTJtliPTEi7njXHLcsFeWXLUmeBEHLozYxfzDQzMvW3EYdNWcC7oVAAt3de0i0ojw9rGswiofhbu2dAe+Xd2bejv1+PVJcEC3SRPGy17kb6bme6gD3zty5ft4VpzP0nomUNqfZBRLUYxSZuKlHJaZ6Nuq434rKmXrcN6uy+eEWDorTbjyM22IIYgUmrhg++Qtu/MBR7/rriPhyRltCU14361bcxqyq2Hw+HNG8D3hsqo5TiEiYwxOQcXRgddL+Ci6/y0L1EvqOQc+1V8ycwNs2oNicwNgSn5A+9HpF495Kae039hGtj2Gpt4IbplSYwKFq/sFTq+CekxdD2YVQmGvsjep4bNVL66o2RSZVAW1Bg/G8/sSe3BwgD8IToy9+1NHPPuaVupeukRqNyUDcVvWH8hdb8AkXYY87+546etYDpn91GQnhTEberKbXX4UCmpKNXpXoprLE8nQLGb6TIoHPTyA+RRNQ4erDzMjqF43UVmhOZTtkGaRgIWK7vDAKpLUnuOguuhJUNpYpRggGQsMV8cZnaCumy5OFUf6i6rfN0Ru6a+/Bm7grJiAcnZlU7igaxgI38QaJgCKcqqzIImdcRYNQC74/Ok/1oM= - secure: BK++GwKVPoS0iG8aB7wQ13daTgJR9MifHA+l9xr/tSZ3SUL6nc7kjxLbliRQJCqT9lcOODsd+v2u9PziEzBp0CCh67ftFxJw8riP2+FgdmHTK4yav9QpSwoBJHhV2SgBMGlXiqdUVC7wpgjzzK63V8abvzAhXkthWPl3kYpUI//xGYyuBNXVHEOImHB3F1M5bn90lflFtRfq2iH5FigGesMi2BFfTVeqvbzZVZrAs0E1/NRdO+/cRq0c9aRpNLkh254k1tcKbUvULQq1iLQuHN2Ramn3NgNnx93sbwp1e7ZjmETbjr9cwMIDg5mh25H0Rjf2Nn8cqHbBCWzoMkjZW097HRVDYht2kJZQIbQcaxX38DW6vykUwGWSBAWbtvCUwYwU57s/dIbSYUTQErkYYmhiq52cdOtnxZ2/ULoElCVyR8lTmQuANJrq9YFC9q1ly69YuMWWnFgwxWpK1JCgAJGELgj5EvcghEtNmkEFh5f6pmbKBE7PKQPTovzNKcdRauR/L+MsmhVYukCfNZq57LrruIQIX1GQNw9w3Ck8P4EPtNjdI4umCSy6nZSyTevWgVTmIP9EwXa5Cap32ZU+iDtw+wUBAr3sjROJOYGKlL/ktWsWbjog5hIG0rrb8PbgOfbLRZSEYGL9sYsyXXyW5oI37lB7AqG6D7vOA4TdmTQ= + on: + tags: true diff --git a/RELEASE.md b/RELEASE.md index 158f24f4b0..ab5b64d63b 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,203 +1,86 @@ -# Releasing a new version of the helm chart +# Release process -The following steps can be followed to release a new version of the Helm Chart. +Start by making a release issue using the template below, it can be followed to +release a new version of the Helm chart and help everybody coordinate. Do some +copy pasting! -## Create an issue for the new release +## Issue title: Release x.y.z -Use this issue to coordinate efforts and keep track of progress. You can -copy / paste the raw Markdown from the following list, which will be covered -in more detail below. - -``` -Title: Release {{release-name}} -Content: - -This issue will be used to coordinate the next release of the helm -chart, {{release-name}}. Instructions for creating the release can be found in -[CONTRIBUTING.md](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/master/CONTRIBUTING.md#releasing-a-new-version-of-the-helm-chart). +This issue will be used to coordinate the next release of the Helm +chart according to the instructions in [RELEASE.md](RELEASE.md). Below is the checklist for this release. -- [ ] Code, tests, and documentation to support a release are stable. -- [ ] Make a CHANGELOG -- [ ] Generate and add the list of contributors -- [ ] Build and push a new Docker image to DockerHub -- [ ] Commit version bump in `Chart.yaml` and `Values.yaml` -- [ ] Update references in documentation to the new version (note: documentation - should be stable and there should be no anticipated major changes to content). -- [ ] Confirm that a new deployment using the updated instructions works -- [ ] Create and push a new tag for this release -- [ ] Create and publish a new GitHub release -- [ ] Write / publish a blog post based largely off of the CHANGELOG -- [ ] Set ReadTheDocs to begin using `latest` by default -- [ ] Celebrate! -``` - -As there are often many documentation improvements following the release of -a new version, we set ReadTheDocs to serve `latest/` until the first docs are -written that are next-version-specific. As soon as documentation must be -written for the **next** version of the Helm Chart, you can use the following -checklist: - -``` -- [ ] Create a new tag for a documentation release (same release name with `-doc` at the end) -- [ ] Publish this tag -- [ ] Set ReadTheDocs to point to the **new tag** by default instead of `latest` -- [ ] Continue making next-version-specific changes to the documentation. -``` - -**Note**: Switching the documentation to `latest` after a new release is a stop-gap -measure to accomodate the fact that the documentation is still changing relatively -rapidly. Once the documentation as a whole stabilizes (after a few more release -cycles), we plan to begin switching straight from the last version to the new version -of documentation without going through latest. - -## Make a CHANGELOG - -This needs to be manually created, following the format of -current [CHANGELOG](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/master/CHANGELOG.md). The general structure should be: - -* A short description of the general theme / points of interest for - this release. -* Breaking changes + a link to the [upgrade instructions](https://zero-to-jupyterhub.readthedocs.io/en/v0.5-doc/upgrading.html) in the docs -* A list of features with brief descriptions under each. -* The contributor list mentioned in the section below. - -## Add list of contributors - -We try to recognize *all* sorts of contributors, rather -than just code committers. - -Use the script in `tools/contributors.py` to list all -contributions (anyone who made a commit or a comment) -since the latest release. For each -release, you'll need to find the versions of all repos -involved: - -* [z2jh](https://github.com/jupyterhub/zero-to-jupyterhub-k8s) -* [KubeSpawner](https://github.com/jupyterhub/kubespawner) -* [JupyterHub](https://github.com/jupyterhub/jupyterhub) -* [OAuthenticator](https://github.com/jupyterhub/oauthenticator) - -Edit `contributors.py` to have the appropriate dates -for each of these versions. Then, run the script and paste -the output into the changelog. For an -example, see [the v0.5 list of contributors](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/v0.5/CHANGELOG.md#contributors). - - -## Push built images to DockerHub + bump version - -The JupyterHub helm chart uses a Docker image that's registered -on DockerHub. When releasing a new version of the helm chart, -you also need to push a new version of this image. To do so, -you must have: - -1. Docker running locally -2. An account on DockerHub that you are logged into from - your local docker installation. -3. Push rights for images under `jupyterhub/` on - the DockerHub registry. -4. Push rights to the `jupyterhub/helm-chart` repository on GitHub. -5. A local SSH key that will let you push to the `helm-chart` repository - on GitHub. See [these instructions](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for information on how to create this. - -**Note**: If you don't have a DockerHub account, or don't have push rights to -the DockerHub registry, open an issue and ping one of the core devs. - -If you have all of this, you can then: - -1. Check out latest master of [z2jh](https://github.com/jupyterhub/zero-to-jupyterhub-k8s) -2. Run `chartpress --tag --push --publish-chart`. - * For example, to relase `v0.5`, you would run - `chartpress --tag v0.5 --push --publish-chart`. - Note the `v` before version. -3. This will also modify the files `Chart.yaml` and `values.yaml`. - Commit these changes. -4. Look through the [z2jh documentation](https://zero-to-jupyterhub.readthedocs.io) and find any references to - the Helm Chart version (e.g., look for the flag `--version`, as well - as for all `helm upgrade` and `helm install` commands). - Update these references to point to the new version you are releasing. -5. Make a PR to the z2jh repository and notify the team to take a look. - -After this PR gets merged: - -1. Go to https://zero-to-jupyterhub.readthedocs.io/en/latest and - deploy a JupyterHub using the instructions (make sure that - you're reading from `/en/latest`). Make sure your latest - changes are present, and that the JupyterHub successfully deploys - and functions properly. - -Next, move on to making a GitHub release, described below. - -## Tagging and making a GitHub release - -Now that our Docker image is pushed and we have updated the documentation -for z2jh, it's time to make a new GitHub release. To do this, you must have: - -1. Push rights to the `jupyterhub/zero-to-jupyterhub-k8s` repo - -You will need to make a git tag, and then create a GitHub release. - -1. Make sure you're on branch `master` with your latest changes from - the section above pulled. -2. Make a git tag with: - ``` - git tag -a - ``` - - Where `` should be the new version that you're releasing. - Note the `v` before the version number. - - Git will ask you to include a message with the tag. - Paste the entire contents of the CHANGELOG for this particular release. - An easy way to do this is to paste the contents in a text file, and - then refer to that text file with the call to commit: - `git tag -a -F ` -3. Push the tags to the `jupyterhub/zero-to-jupyterhub-k8s` repo with - `git push --tags`. - Note that `` is whatever your local git uses to refer - to the `jupyerhub/` organization's repository (e.g., `official` - or `upstream`) -3. Make a **GitHub Release**: - * go to https://github.com/jupyterhub/zero-to-jupyterhub-k8s/releases and click 'Draft new release'. - * The title should be the new version, followed by the name of the cricketer for the release. Like so:`v0.5: "Hamid Hassan"`. - * The description should include the entire changelog entry for this release. - * Make sure the title/description/tag name look correct, and then click - on `Publish Release`. - -You've just made a GitHub release! - - -## ReadTheDocs update - -Wait a few hours to let the release 'cool' and make sure that links, -webpages, etc have updated. Then, update our documentation settings on -readthedocs to show `latest` by default. This marks the official -'release' of the version! - -## Last step - release a blog post and tell the world! - -The final step is to release a blog post. This doesn't have to be -done by the person who performed all of the above actions. - -To release a blog post for the new version, start a draft on the Jupyter Medium -blog. Copy/paste the section of the CHANGELOG corresponding to the new -release, then make minor modifications to make it more blog-friendly. - -Don't forget to tell the JupyterHub community about the new release, and -to encourage people to talk about it on social media! - -That's it! Congratulations on making a new release of JupyterHub! - -## Extra step - release a documentation release - -It is common that documentation changes are made shortly after a new release. -To handle this, we often create a documentation release a few days after a -major release. - -To do this, confirm that all changes to the documentation -are merged into master, then create a new tag with the same release name and -`-doc` appended to the end. Create a GitHub release with the new tag and a -description that points to the original release description. Finally, set -our ReadTheDocs settings to point users to the new `-doc` tag by default instead -of `latest`. - +## Pre-release iteration 1 + +- Make a changelog + - [ ] Summarize points of interest. + - [ ] List breaking changes and mention the [upgrade instructions](https://z2jh.jupyter.org/en/latest/upgrading.html). + - [ ] Update the upgrade instructions. + - [ ] List features with brief descriptions. + +- Pre-release + - [ ] Create and push a git tag + + ```bash + git checkout master + git pull master + git tag -a x.y.z-beta.1 + git push --tags + ``` + +- Update documentation + - [ ] Update old version references to the new version + +- Communicate + - [ ] Write a discourse post + +- Verify + - [ ] Follow one set of instructions to deploy on z2jh.jupyter.org + +## Final release + +- Update changelog + - [ ] Update the changelog + - [ ] Generate and add a list of contributors + + ```bash + # install dependencies for the script + pip install pygithub requests-cache tqdm + + # NOTE: You may need to wait a long time for this to finish. You may even + # get errors because you used too much of your API quota. If that + # happens, you can re-run it again later and rely on the caching to + # ensure you make progress. You have 5000 requests per hour. + + # get a GITHUB_API_TOKEN for use with the script + GITHUB_API_TOKEN="your-token" tools/contributors.py + ``` + +- Release + - [ ] Create and push a git tag + + ```bash + git checkout master + git pull master + git tag -a x.y.z + git push --tags + ``` + + - [ ] Create a GitHub release + + Visit the [release + page](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/releases) and + create a new release referencing the recent tag. Add a brief text like the + one below. + + ```Markdown + # TODO: Figure out how to... + - Warn about eventual breaking changes. + - Reference upgrade instructions and the changelog. + - NOTE: Also make the upgrade instructions contain a reference on what to do if they fail. + ``` + +- Communicate + - [ ] Write a discourse post + - [ ] Write a blog post + - [ ] Tweet about it diff --git a/ci/publish b/ci/publish index 01e5bbb0e9..36afab3045 100755 --- a/ci/publish +++ b/ci/publish @@ -16,7 +16,11 @@ set -x # git ahead of time to use the identity we decrypted earlier. export GIT_SSH_COMMAND="ssh -i ${PWD}/ci/id_rsa" -chartpress --commit-range "${TRAVIS_COMMIT_RANGE}" --push --publish-chart +if [ "${TRAVIS_TAG:-}" == "" ]; then + chartpress --commit-range "${TRAVIS_COMMIT_RANGE}" --push --publish-chart +else + chartpress --commit-range "${TRAVIS_COMMIT_RANGE}" --push --publish-chart --tag "${TRAVIS_TAG}" +fi # Let us log the changes chartpress did, it should include replacements for # fields in values.yaml, such as what tag for various images we are using. diff --git a/jupyterhub/Chart.yaml b/jupyterhub/Chart.yaml index e9dafbe531..21ccf4d67d 100644 --- a/jupyterhub/Chart.yaml +++ b/jupyterhub/Chart.yaml @@ -1,5 +1,5 @@ name: jupyterhub -version: 0.9-0924e65 +version: 0.9-dev appVersion: 1.0.1dev description: Multi-user Jupyter installation home: https://z2jh.jupyter.org diff --git a/tools/contributors.py b/tools/contributors.py index cdce42ef87..293ef70edf 100755 --- a/tools/contributors.py +++ b/tools/contributors.py @@ -1,30 +1,27 @@ #!/usr/bin/env python3 """ -Script to list *all* contributors to a given set of repos, -between a set of dates. This includes: +Script to list *all* contributors to a given set of repos, between a set of +dates. This includes: - Everyone who has made a commit merged between those dates - Everyone who has opened or commented on an issue between those dates - Everyone who has opened or commented on a PR between those dates -If you think this misses people who make contributions of a specific -form, feel free to add them here! +This script outputs a markdown formatted list of contributors in casefolded name +(username if name not specified) order. -This script outputs a markdown formatted list of contributors -in casefolded name (username if name not specified) order. - -Since we will be making a ton of requests to the GitHub API, you -need a GitHub API Token to use this script. The easiest way is to -just get a Personal Access Token (https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). -Treat this token similar to how you would treat a password! -You can pass this token in with `GITHUB_API_TOKEN` environment -variable. For example, +Since we will be making a ton of requests to the GitHub API, you need a GitHub +API Token to use this script. The easiest way is to just get a Personal Access +Token +(https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). +Treat this token similar to how you would treat a password! You can pass this +token in with `GITHUB_API_TOKEN` environment variable. For example, $ GITHUB_API_TOKEN="your-token" ./tools/contributors.py -Note that if you put a space before your command, it does not -get stored in your bash history (by default)!. Look up `HISTCONTROL` -to learn more about this feature of shells. +Note that if you put a space before your command, it does not get stored in your +bash history (by default)!. Look up `HISTCONTROL` to learn more about this +feature of shells. IMPORTANT: You may need to run this script twice or so, utilizing the previous runs cached @@ -32,10 +29,10 @@ """ import os -import dateutil +from dateutil.parser import parse + import requests_cache from github import Github -from dateutil.parser import parse from tqdm import tqdm requests_cache.install_cache('github')