From a206ef4bd983c21b7f91ade40bd72553d1c17e77 Mon Sep 17 00:00:00 2001 From: Owen Jones Date: Tue, 31 Jan 2023 17:59:23 +0000 Subject: [PATCH] Updating docs for release process --- docs/README.md | 21 +++++---- docs/release_process.md | 95 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+), 8 deletions(-) create mode 100644 docs/release_process.md diff --git a/docs/README.md b/docs/README.md index db911718c..8ec83ac8f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,19 @@ -# Developing for `darwin-py` +# Developing for `darwin-py` `darwin-py` uses a `pyproject.toml` file, and manages it with `poetry` -- [Developing for `darwin-py`](#developing-for-darwin-py) - - [Development environment](#development-environment) - - [Basic poetry commands](#basic-poetry-commands) - - [Add a package to general dependencies:](#add-a-package-to-general-dependencies) - - [Add a package to one of the extras groups](#add-a-package-to-one-of-the-extras-groups) - - [Add a package to the poetry dev dependencies](#add-a-package-to-the-poetry-dev-dependencies) - - [The `pyproject.toml` file](#the-pyprojecttoml-file) +## Contents +- [Other links](#other-links) +- [Development environment](#development-environment) +- [Basic poetry commands](#basic-poetry-commands) + - [Add a package to general dependencies:](#add-a-package-to-general-dependencies) + - [Add a package to one of the extras groups](#add-a-package-to-one-of-the-extras-groups) + - [Add a package to the poetry dev dependencies](#add-a-package-to-the-poetry-dev-dependencies) +- [The `pyproject.toml` file](#the-pyprojecttoml-file) + +## Other links + +* [Release process](release_process.md) ## Development environment diff --git a/docs/release_process.md b/docs/release_process.md new file mode 100644 index 000000000..e5f919c8d --- /dev/null +++ b/docs/release_process.md @@ -0,0 +1,95 @@ +# Release Process + +How to create releases of `darwin-py`. + +## Contents + +- [Introduction](#introduction) +- [Make a standard release](#make-a-standard-release) + - [Steps](#steps) +- [Make a hotfix release](#make-a-hotfix-release) + - [Steps](#steps-1) +- [Contact](#contact) + + +## Introduction + +`darwin-py` is released on [pypi.org](https://pypi.org/project/darwin-py/). It uses [Poetry's]([https://poetry-python](https://python-poetry.org/)) "Mason" engine, which builds both [SDIST](https://docs.python.org/3/distutils/sourcedist.html) and [Wheel](https://pythonwheels.com/) artefacts, and uploads them to PyPi using `setuptools`. The build system is [`PEP-518`](https://peps.python.org/pep-0518/) compliant, which is required to install with `pip` versions 25 and over. + +These instructions are only applicable to those with permissions to release on the repository, within the V7 organisation, not community contributors. You can request we make a new release with contributions you have made by emailing [info@v7labs.com](mailto:info@v7labs.com). + +## Make a standard release + +These are the steps for releasing a passing `master` branch. If you are releasing a hotfix or other selective build, you need to follow the instructions for a [hotfix release](#make-a-hotfix-release). + +### Steps + +1. Ensure all tickets to be included are QA'd and to be included in a release. Speak to PM's and code owners if unsure. +2. Once passed on QA, merge all PRs to be included into `master` +3. Ensure that `master` tests are still passing after merge. +4. Checkout a new branch for the version bump. +5. Open `pyproject.toml`, and update the version in there. Maintain semver, and agree with owner if you are intending to make a release that is not a minor increment. +``` +[tool.poetry] +name = "darwin-py" +version = "0.8.7" # update this when you change the version - See: https://peps.python.org/pep-0440/ +``` +6. Add, commit, and open a PR for the version bump. +7. Once accepted, merge, and tag `master` with the version you have set, prefixed with "v". E.g. if you set the version to `1.2.3`, then tag as `v1.2.3` +```shell +$ git checkout master +$ git tag v1.2.3 master # for example +$ git push origin v1.2.3 # again, for example +``` +8. Push the tag. +9. In the ["Draft a new release"](https://github.com/v7labs/darwin-py/releases/new) section of github, select the tag you created. Write an appropriate summary of the release (see Engineering team guidance on language), and create the release. Click "Publish release" +10. Ensure release is successful in CI/CD +11. Ensure that release appears in Pypi. + +## Make a hotfix release + +Making a hotfix release is _broadly_ the same as the process for [making a normal release](#make-a-standard-release), but first you need to `cherry-pick` the items you need into a hotfix branch. + +### Steps + +1. Create a hotfix branch to contain your new release, based on the **last release, not master**. +```shell +$ git checkout v1.2.2 # for example - should be the last released tag +$ git checkout -b hotfix_branch_v1_2_3 # naming discretionary, branch won't exist long +``` +2. Two possible routes forward: + 1. If your branch is based on other, unmerged branches, then you can merge them into your hotfix branch: + ```shell + $ git merge thing_i_need_in_hotfix + $ git merge other_thing_i_need_in_hotfix + ``` + + You may have to settle merge conflicts. + + 2. If your branch is based on already-merged-into-master items, then you need to use `cherry-pick` to include them in your branch. We use a squash-merge on PR, so you can cherry pick the squash merge of each PR, this will be the commit number that was actually merged in. If for some reason you're dealing with merges not squash-merged, you need to cherry pick each commit from the branch in, in order that they happened. + ```sh + $ git cherry-pick [commit-number] + $ git cherry-pick [other-commit-number] + ...and so on + ``` +3. After these, you will have a branch with the items you need to include in a hot-fix. Open `pyproject.toml`, and update the version in there. Maintain semver, and agree with owner if you are intending to make a release that is not a minor increment. +``` +[tool.poetry] +name = "darwin-py" +version = "0.8.7" # update this when you change the version - See: https://peps.python.org/pep-0440/ +``` +4. Add, commit, and push the branch. +5. Once accepted, tag the branch with the version you have set, prefixed with "v". E.g. if you set the version to `1.2.3`, then tag as `v1.2.3` +```shell +$ git checkout [your hotfix branch name] +$ git tag v1.2.3 [your hotfix branch name] # for example +$ git push origin v1.2.3 # again, for example +``` +6. Push the tag. +7. In the ["Draft a new release"](https://github.com/v7labs/darwin-py/releases/new) section of github, select the tag you created, and the hotfix branch. Write an appropriate summary of the release (see Engineering team guidance on language), and create the release. Click "Publish release" +8. Ensure release is successful in CI/CD +9. Ensure release is successful in Pypi + +## Contact + +Any issues, reach out in the appropriate channels on slack, or contact owen@v7labs.com - Slack is faster. \ No newline at end of file