Skip to content

Commit

Permalink
Update release documentation (#868)
Browse files Browse the repository at this point in the history 
* Update release.md

* Delete upload.sh

* update changelog

* Add how to handle release pr in changelog

* Fix typo in release.md
  • Loading branch information
@rwedge
rwedge authored Mar 26, 2020
1 parent d77be7d commit f977679
Show file tree
Hide file tree
Showing 3 changed files with 82 additions and 145 deletions.
1 change: 1 addition & 0 deletions docs/source/changelog.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Changelog
* Add links to primitives.featurelabs.com (:pr:`860`)
* Add source code links to API reference (:pr:`862`)
* Update links for testing Dask/Spark integrations (:pr:`867`)
* Update release documentation for featuretools (:pr:`868`)
* Testing Changes
* Miscellaneous changes (:pr:`861`)

Expand Down
210 changes: 81 additions & 129 deletions release.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,34 @@
# Release Process
## Test conda-forge release
Conda releases of featuretools rely on PyPI's hosted featuretools packages. Since we cannot reupload featuretools to PyPI using the same version number, it is important ensure the version we upload works with conda so that we don't have to immediately release a new version of featuretools or skip supporting conda for one release cycle. We can test if a featuretools release will run on conda by uploading a release candidate version of featuretools to PyPI's test server and building a conda version of featuretools based on the test servers' featuretools package.
## Test conda version before releasing on PyPI
Conda releases of featuretools rely on PyPI's hosted featuretools packages. Once a version is uploaded to PyPI we cannot update it, so it is important that the version we upload to PyPI will work for conda. We can test if a featuretools release will run on conda by uploading a test release to PyPI's test server and building a conda version of featuretools using the test release.

#### Upload featuretools release to PyPI's test server
We need to upload a featuretools package to test with the conda recipe
1. Make a new development release branch on featuretools (in this example we'll be testing the 0.13.3 release)
```bash
git checkout -b v0.13.3.dev
```
2. Update version number in `setup.py`, `featuretools/version.py`, `featuretools/tests/test_version.py` to v0.13.3.dev0 and push branch to repo
3. Publish a new release of featuretools on Github.
1. Go to the [releases page](https://github.com/FeatureLabs/featuretools/releases/) on Github
2. Click "Draft a new release"
3. For the target, choose the new branch (v0.13.3.dev)
4. For the tag, use the new version number (v0.13.3.dev0)
5. For the release title, use the new version number (v0.13.3.dev0)
6. For the release description, write "Development release for testing purposes"
7. Check the "This is a pre-release" box
8. Publish the release
4. The new release will be uploaded to TestPyPI automatically

#### Set up fork of our conda-forge repo
Branches on the conda-forge featuretools repo are automatically built and the package uploaded to conda-forge, so to test a release without uploading to conda-forge we need to fork into a separate repo and develop there.
Branches on the conda-forge featuretools repo are automatically built and the package uploaded to conda-forge, so to test a release without uploading to conda-forge we need to fork the repo and develop on the fork.
1. Fork conda-forge/featuretools-feedstock: visit https://github.com/conda-forge/featuretools-feedstock and click fork
2. Clone forked repo locally
3. Add conda-forge repo as the 'upstream' repository
```bash
git remote add upstream https://github.com/conda-forge/featuretools-feedstock.git
```
4. If your made the fork previously and its master branch is missing commits, update it with any changes from upstream
4. If you made the fork previously and its master branch is missing commits, update it with any changes from upstream
```bash
git fetch upstream
git checkout master
Expand All @@ -22,157 +40,91 @@ Branches on the conda-forge featuretools repo are automatically built and the pa
git checkout -b new-featuretools-version
```

#### Upload featuretools release candidate to PyPI's test server
Before we can update the conda recipe we need an uploaded package for the recipe to use
1. Make a new release candidate branch on featuretools (in this example we'll use version 0.7.0)
```bash
git checkout -b v0.7.0rc
```
2. Update version number in `setup.py`, `featuretools/version.py`, `featuretools/tests/test_version.py` to v0.7.0rc1 and push branch to repo
3. Upload release candidate to test.pypi.org
```bash
docker run \
--rm \
-it \
-v /path/to/upload.sh:/home/circleci/upload.sh \
circleci/python:3
/bin/bash -c "bash /home/circleci/upload.sh v0.7.0rc testpypi"
```
#### Update conda recipe to use testpypi release of featuretools
#### Update conda recipe to use TestPyPI release of featuretools
Fields to update in `recipe/meta.yaml` of feedstock repo:
* Set the new release number (e.g. v0.7.0rc1)
```
{% set version = "0.7.0rc1" %}
```
* Source fields
* url - visit https://test.pypi.org/project/featuretools/, find correct release, go to download files page, and copy link location of the tar.gz file
* sha256 - click on SHA256 link next to tar.gz to copy it
```
source:
url: https://test-files.pythonhosted.org/packages/e9/79/4fc79465159f6700c1f7b9cf7403b9e455b40e659f3c979ce282f2eb9bf2/featuretools-0.7.1rc1.tar.gz
sha256: d9d542172d50b00c6a7154577b8a0ba5f1f500e3f940d83c9e46b4d4a36bf57a
```
* setup-requirements.txt dependencies go here
```
requirements:
host:
- pip
- python
```
* requirements.txt dependencies go here
```
requirements:
run:
- click
- cloupickle
```
* test-requirements.txt dependencies go here
```
test:
requires:
- fastparquet
- mock
```
* Always update:
* Set the new release number (e.g. v0.13.3.dev0)
```
{% set version = "0.13.3.dev0" %}
```
* Source fields
* url - visit https://test.pypi.org/project/featuretools/, find correct release, go to download files page, and copy link location of the tar.gz file
* sha256 - from the download files page, click the view hashes button for the tar.gz file and copy the sha256 digest
```
source:
url: https://test-files.pythonhosted.org/packages/3a/d7/8600d5ffa72d6890344df0811e8431465bcf15f2a9eade143ee34f67c1c4/featuretools-0.13.3.dev0.tar.gz
sha256: e9c3b4fe4aa40a4606dc3d72c65b4dc3ed03014229d4f225d5e8ce0a727d4462
```
* Update if dependencies have changed:
* setup-requirements.txt dependencies are host requirements
```
requirements:
host:
- pip
- python
```
* requirements.txt dependencies are run requirements
```
requirements:
run:
- click
- cloupickle
```
* test-requirements.txt dependencies are test requirements
```
test:
requires:
- fastparquet
- mock
```

#### Test building the conda package locally
#### Test with conda-forge CI
1. Install conda
1. If using pyenv, `pyenv install miniconda3-latest`
2. Otherwise follow instructions in [conda docs](https://conda.io/projects/conda/en/latest/user-guide/install/index.html)
2. Install conda-build package
```bash
conda install conda-build
```
3. Build featuretools package
```bash
conda-build /path/to/recipe/dir
```
#### Test with conda-forge CI
1. Install conda-smithy (conda-forge tool to update boilerplate in repo)
2. Install conda-smithy (conda-forge tool to update boilerplate in repo)
```bash
conda install -n root -c conda-forge conda-smithy
```
2. Run conda-smithy on feedstock
3. Run conda-smithy on feedstock
```bash
cd /path/to/feedstock/repo
conda-smithy rerender --commit auto
```
3. Make a PR on conda-forge/featuretools-feedstock from the forked repo and let CI tests run - indicate that this pr should not be merged
4. Push updated branch to the forked feedstock repo
3. Make a PR on conda-forge/featuretools-feedstock from the forked repo and let CI tests run - add "[DO NOT MERGE]" to the PR name to indicate this is PR should not be merged in
4. After the tests pass, close the PR without merging

## Create featuretools release on github
#### Create release branch
1. Branch off of master and name the branch the release version number (e.g. v0.7.1)
2. Bump verison number in `setup.py`, `featuretools/version.py`, and `featuretools/tests/test_version.py`.
1. Branch off of featuretools master and name the branch the release version number (e.g. v0.13.3)

#### Bump version number
2. Bump version number in `setup.py`, `featuretools/version.py`, and `featuretools/tests/test_version.py`.

#### Update changelog
1. Grab commit history since last release
```bash
git log --pretty=oneline --abbrev-commit
```
Which displays something like
```
40298ad Automatically generate name for controllable primitives (#481)
23dc0b1 Check for duplicates Fix (#479)
cf98910 Update how standard primitives are imported internally (#482)
c30d842 v0.7.0 (#477)
```
2. Copy all the commits since the past release into a new entry in `docs/source/changelog.rst`
1. Replace "Future Release" in `docs/source/changelog.rst` with the current date
```
**v0.7.1** Apr 12, 2019
* Automatically generate name for controllable primitives (#481)
* Check for duplicates Fix (#479)
* Update how standard primitives are imported internally (#482)
**v0.13.3** Feb 28, 2020
```
In order for the documentation to build with proper links, we need to use special syntax to link to github users and pull requests.
```rst
* Automatically generate name for controllable primitives (:pr:`481`)
2. Remove any unused changelog sections for this release (e.g. Fixes, Testing Changes)
3. Add yourself to the list of contributors to this release and put the contributors in alphabetical order
4. The release PR does not need to be mentioned in the list of changes

Thanks to :user:`kmax12` for contributing to this release
```
Confusing commit descriptions should be updated and commits related to the same feature can be grouped together. Testing updates and documentation updates can be simplified into one commit each, unless a change deserves its own description.
3. Thank each github user who contributed to the updates in this release
```rst
**v0.7.1** Apr 12, 2019
* Automatically generate name for controllable primitives (#481)

Thanks to the following people for contributing to this release: :user:`user1`, :user:`user2`, :user:`user3`
```
#### Create Release PR
A [release pr](https://github.com/Featuretools/featuretools/pull/507) should have the version number as the title and the changelog updates as the PR body text. The contributors line is not necessary. The special docs syntax needs to be reverted back to `#547` style for PR links.
A [release pr](https://github.com/Featuretools/featuretools/pull/856) should have the version number as the title and the changelog updates as the PR body text. The contributors list is not necessary. The special sphinx docs syntax (:pr:\`547\`) needs to be changed to github link syntax (#547).

#### Create Github Release
After the release pull request has been merged into the master branch, it is time draft the github release. [Example release](https://github.com/Featuretools/featuretools/releases/tag/v0.7.1)
After the release pull request has been merged into the master branch, it is time draft the github release. [Example release](https://github.com/Featuretools/featuretools/releases/tag/v0.13.3)
* The target should be the master branch
* The tag should be the version number with a v prefix (e.g. v0.7.1)
* The tag should be the version number with a v prefix (e.g. v0.13.3)
* Release title is the same as the tag
* Release description should be the full changelog updates for the release, including the line thanking contributors.
## Release on PyPI
1. Update circleci's python3 image
```bash
docker pull circleci/python:3
```
2. Run upload script
* Replace `/absolute/path/to/upload.sh` with the actual path
* Replace the "release_tag" part of `tags/release_tag` with the actual tag
```bash
docker run \
--rm \
-it \
-v /absolute/path/to/upload.sh:/home/circleci/upload.sh \
circleci/python:3 \
/bin/bash -c "bash /home/circleci/upload.sh tags/release_tag"
```

## Deploy docs
From root
```
cd docs
python source/upload.py --root
```
* Release description should be the full changelog updates for the release, including the line thanking contributors. Contributors should also have their links changed from the docs syntax (:user:\`rwedge\`) to github syntax (@rwedge)
* This is not a pre-release
* Publishing the release will automatically upload the package to PyPI

## Release on conda-forge
1. Release featuretools on PyPI
1. Wait for bot to create new PR in conda-forge/featuretools-feedstock
2. Update requirements in `recipe/meta.yaml` (bot should have handled version and source links on its own)
3. After tests pass, merge the PR
1. A bot should automatically create a new PR in conda-forge/featuretools-feedstock
2. Update requirements changes in `recipe/meta.yaml` (bot should have handled version and source links on its own)
3. After tests pass, a maintainer will merge the PR in
16 changes: 0 additions & 16 deletions release/upload.sh
View file

This file was deleted.

0 comments on commit f977679

Please sign in to comment.