Added scripts to automate the release process (#298)

* initial import of release helper scripts

* git add release/README.md

* formatting

release/README.md

@@ -0,0 +1,58 @@
+# Release Scripts
+
+This subdirectory contains various scripts for making a smart_open release.
+
+## Release Procedure
+
+First, check that the [latest commit](https://github.com/RaRe-Technologies/smart_open/commits/master) passed all CI.
+
+Prepare the release, replacing 1.2.3 with the actual version of the new release:
+
+    bash prepare.sh 1.2.3
+
+This will create a local release branch.
+Look around the branch and make sure everything is in order.
+Checklist:
+
+- [ ] Does smart_open/VERSION contain the correct version number for the release?
+- [ ] Does the CHANGELOG.md contain a section detailing the new release?
+- [ ] Are there any PRs that should be in CHANGELOG.md, but currently aren't?
+
+If anything is out of order, make the appropriate changes and commit them to the release branch before proceeding.
+For example, you may use the summarize_pr.sh helper script to generate one-line summaries of PRs and copy-paste them into the CHANGELOG.md.
+
+**Once you're happy with the release branch**, run:
+
+    bash merge.sh
+
+This will perform a merge and push your changes to github.com.
+
+**This is the point of no return**.  Run:
+
+    bash push_pypi.sh
+
+and provide your PyPI username and password.
+
+Go to the [releases page](https://github.com/RaRe-Technologies/smart_open/releases/tag) and copy-paste the relevant part of the CHANGELOG.md to the release notes.
+Publish the release.
+
+Congratulations, at this stage, you are done!
+
+## Troubleshooting
+
+Ideally, our CI should save you from major boo-boos along the way.
+If the build is broken, fix it before even thinking about doing a release.
+
+If anything is wrong with the local release branch (before you call merge.sh), for example:
+
+- Typo in CHANGELOG.md
+- Missing entries in CHANGELOG.md
+- Wrong VERSION number
+
+then just fix it in the release branch before moving on.
+
+If you've realized there's a problem _after_ calling merge.sh, but _before_ calling push_pypi.sh, then you've made a bit of a mess, but it's still possible to clean it up:
+
+1. Delete the tag for the new version from github.com
+2. Delete the tag locally (git tag -d 1.2.3)
+3. Repeat from the top using the same version number, and try to get it right this time

release/merge.sh

@@ -0,0 +1,44 @@
+#
+# Performs the following tasks:
+#
+# - Merges the current release branch into master
+# - Applies a tag to master
+# - Pushes the updated master branch and its tag to upstream
+#
+# Use it like this:
+#
+#     bash release/merge.sh
+#
+# Expects smart_open/VERSION to be correctly incremented for the new release.
+#
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+version="$(head -n 1 smart_open/VERSION)"
+
+read -p "Push version $version to github.com? yes or no: " reply
+if [ "$reply" != "yes" ]
+then
+    echo "aborted by user"
+    exit 1
+fi
+
+#
+# Delete the local master branch in case one is left lying around.
+#
+set +e
+git branch -D master
+set -e
+
+git checkout upstream/master -b master
+git merge --no-ff release-${version}
+git tag -a ${version} -m "${version}"
+git push --tags upstream master
+
+#
+# TODO: we should be able to automate the release note stuff.  It's just a
+# copypaste of CHANGELOG.md.
+#
+echo "The release is almost done!  Two more steps to go:"
+echo "1) Update release notes at https://github.com/RaRe-Technologies/smart_open/releases/tag/$version"
+echo "2) Push the new release to PyPI: run 'bash push_pypi.sh'"

release/prepare.sh

@@ -0,0 +1,62 @@
+#
+# Prepare a new release of smart_open.  Use it like this:
+#
+#     bash release/prepare.sh 1.2.3
+#
+# where 1.2.3 is the new version to release.
+#
+# Does the following:
+#
+# - Creates a clean virtual environment
+# - Runs tests
+# - Creates a local release git branch
+# - Bumps VERSION accordingly
+# - Opens CHANGELOG.md for editing, commits updates
+#
+# Once you're happy, run merge.sh to continue with the release.
+#
+set -euo pipefail
+
+version="$1"
+echo "version: $version"
+
+script_dir="$(dirname "${BASH_SOURCE[0]}")"
+cd "$script_dir"
+
+git fetch upstream
+
+rm -rf sandbox.venv
+virtualenv sandbox.venv -p $(which python3)
+
+set +u  # work around virtualenv awkwardness
+source sandbox.venv/bin/activate
+set -u
+
+cd ..
+pip install -e .[test]  # for smart_open
+pip install .[test]  # for gensim
+python setup.py test  # for gensim
+
+#
+# Delete the release branch in case one is left lying around.
+#
+git checkout upstream/master
+set +e
+git branch -D release-"$version"
+set -e
+
+git checkout upstream/master -b release-"$version"
+echo "$version" > smart_open/VERSION
+git commit smart_open/VERSION -m "bump version to $version"
+
+echo "Next, update CHANGELOG.md."  
+echo "Consider running summarize_pr.sh for each PR merged since the last release."
+read -p "Press Enter to continue..."
+
+$EDITOR CHANGELOG.md
+git commit CHANGELOG.md -m "updated CHANGELOG.md for version $version"
+
+echo "Have a look at the current branch, and if all looks good, run merge.sh"
+
+cd "$script_dir"
+rm -rf sandbox.venv

release/push_pypi.sh

@@ -0,0 +1,31 @@
+#
+# Upload the current release of smart_open to PyPI.
+# Run this _after_ you've run the other scripts, e.g. prepare.sh and merge.sh.
+#
+set -euo pipefail
+
+script_dir="$(dirname "${BASH_SOURCE[0]}")"
+cd "$script_dir"
+
+rm -rf sandbox.venv
+virtualenv sandbox.venv -p $(which python3)
+
+set +u  # work around virtualenv awkwardness
+source sandbox.venv/bin/activate
+set -u
+
+cd ..
+pip install twine
+python setup.py sdist
+
+version="$(head -n 1 smart_open/VERSION)"
+read -p "Push version $version to PyPI? This step is non-reversible.  Answer yes or no: " reply
+if [ "$reply" != "yes" ]
+then
+    echo "aborted by user"
+    exit 1
+fi
+twine upload "dist/smart_open-$version.tar.gz"
+
+cd "$script_dir"
+rm -rf sandbox.venv

release/summarize_pr.sh

@@ -0,0 +1,24 @@
+#
+# Summarize pull requests.  Example usage:
+#
+#   bash summarize_pr.sh 123 456 789
+#
+# where 123, 456 and 789 are PR IDs.  List as many PRs as you want.
+#
+# Gives a summary like:
+#
+# - Removes native xz support (PR [#282](https://github.com/RaRe-Technologies/smart_open/pull/282), [@tdhopper](https://github.com/tdhopper))
+# - backward compatibility fixes (PR [#294](https://github.com/RaRe-Technologies/smart_open/pull/294), [@mpenkov](https://github.com/mpenkov))
+#
+# You can paste this directly into CHANGELOG.md
+#
+for prid in "$@"
+do
+    api_url="https://api.github.com/repos/RaRe-Technologies/smart_open/pulls/${prid})"
+    json="$(wget --quiet -O - ${api_url})"
+    title="$(echo "$json" | jq .title --raw-output)"
+    html_url="$(echo "$json" | jq .html_url --raw-output)"
+    user="$(echo "$json" | jq .user.login --raw-output)"
+    user_html_url="$(echo "$json" | jq .user.html_url --raw-output)"
+    echo "  - ${title} (PR [#${prid}](${html_url}), [@${user}](${user_html_url}))"
+done