diff --git a/dev_docs/release_process.md b/dev_docs/release_process.md index ac770cef..b4e0830e 100644 --- a/dev_docs/release_process.md +++ b/dev_docs/release_process.md @@ -43,24 +43,53 @@ Follow these steps to create a release. 8. Publish to pypi by performing the following steps (assumes you that you have registered for pypi, and that you have write access to the cellxgene pypi package): - Build the distribution and upload to test pypi `make release-stage-2` - - [optional] Test the test installation in a fresh virtual environment using `make install-release-test` + - Test the test installation in a fresh virtual environment using `make install-release-test` - Upload the package to real pypi using `make release-stage-final` - - [optional] Test the installation in a fresh virtual environment using + - Test the installation in a fresh virtual environment using `pip install cellxgene` - - **Troubleshooting**: - - Fails to upload to test.pypi: pypi doesn't allow you to reupload a release with the same version number, - if you accidentally burned a release number you want to use on prod, you have a couple options. - 1) OPTION 1: Create distribution `make pydist`; test release locally `pip install dist/`; - then upload to prod `make release-stage-final`. - 2) OPTION 2: (DANGER) release directly to prod: `make release-burned`. - 3) OPTION 3: If the release was burned on prod as well run from Step 3 again with option - PART=patch until you get to an unburned version. - - The release doesn't install or fails your tests when you install it: Delete it from pypi - Go to pypi.org, sign in, - go to the cellxgene package, click manage, then in the options drop down, click delete and - follow the instructions. You will not be able to use that release number again. If it is a minor bug - and not a major regression, you can just release a patch. - The optional steps are for testing purposes, and are recommended for publishing any major releases, and any releases that significantly change the packaging (e.g. new bundled files, new dependencies, etc.) + +## Troubleshooting +### Fails to upload to test.pypi + + _PyPi doesn't allow you to reupload a release with the same version number_ +If you accidentally burned a release number you want to use on prod, you have a few options: +1) OPTION 1: Create distribution `make pydist`; test release locally `pip install dist/`; + then upload to prod `make release-stage-final`. +2) OPTION 2: (DANGER) release directly to prod: `make release-directly-to-prod`. +3) OPTION 3: If the release was burned on prod as well run from Step 3 again with option +PART=patch until you get to an unburned version. + +### The release doesn't install or fails your tests when you install it + +Delete it from pypi - Go to pypi.org -> sign in -> go to the cellxgene package -> click manage -> then in the options drop down click delete -> follow the instructions. You will not be able to use that release number again. If it is a minor bug and not a major regression, you can just release a patch. +### If you need to run stage final on a different computer than stage 2 + If you run stage final without running stage 2 first, the dist will not have been build on the computer running stage final. The solution is to run `make release-directly-to-prod`. This both builds the distribution files and then releases directly to prod pypi.org. + +## Stage Details +### Stage 1 - `make release-stage-1` + 1. Pip installs requirements-dev + 2. Bumps version by [PART] + 3. Deletes build directory, client/build, dist and cellxgene.egg-info + 4. Creates the package-lock.json + +### Stage 2 - `make release-stage-2` + 1. Pip installs requirements-dev + 2. Builds client and server + 3. Creates distribution release (sdist) + 4. Uploads to test.pypi.org + +### Stage final - `make release-stage-final` + ** Does not build distribution ** + 1. Uploads to pypi.org + +### (DANGER) Release directly to prod `make release-directly-to-prod` + ** builds distribution and uploads directly to prod ** + Only use this if you are directed to by the troubleshooting guide + 1. Pip installs requirements-dev + 2. Builds client and server + 3. Creates distribution release (sdist) + 4. Uploads to pypi.org diff --git a/makefile b/makefile index 323aeaa5..978c48ee 100644 --- a/makefile +++ b/makefile @@ -76,7 +76,7 @@ release-stage-final: twine-prod # DANGER: releases directly to prod # use this if you accidently burned a test release version number, -release-burned : dev-env pydist twine-prod +release-directly-to-prod : dev-env pydist twine-prod @echo "Dist built and uploaded to pypi.org" @echo "Test the install:" @echo " make install-release" @@ -114,12 +114,12 @@ install-dev : uninstall # install from test.pypi to test your release install-release-test : uninstall - pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple cellxgene + pip install --no-cache-dir --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple cellxgene @echo "Installed cellxgene from test.pypi.org, now run and smoke test" # install from pypi to test your release install-release : uninstall - pip install cellxgene + pip install --no-cache-dir cellxgene @echo "Installed cellxgene from pypi.org" uninstall :