Release 1.1.0

[st-pasha]

GitHub

• Open a "Release X.Y.0" issue, and copy the text of this issue, clearing all checkboxes.

• Visit the Milestone corresponding to the version being released, and remove all issues that are still pending (except for those that will be closed during the release).

• Closed issues / merged PRs must be appropriately assigned to a Milestone, in order for our system of counting contributors to work properly. In particular, any closed PR with a milestone will be attributed to its author. If a PR has no milestone, it will not be counted. Likewise, closed issues will attributed to their authors if and only if they are marked with a Milestone.

  • Check that all PRs merged since last release have a milestone.

  • Check that all PRs that were closed without merging do not have a milestone.

  • Check that all issues that were closed via a PR have a milestone.

  • Check that all issues that were closed without a PR have no milestone.
    (Note, however, that due to some bugs with GitHub, there are issues that were closed via PRs, but those PRs are not listed as linked to the issue. In such a case try linking the issue manually via the "linked pull requests" dropdown on the right. If that didn't work, then nothing can be done -- leave the issue assigned to the Milestone).

Local preparation

• Create local branch rel-X.Y (based on latest main) corresponding to the release number. Do not push to GitHub yet.

• Run python ci/headers.py src/core to check that there are no missing headers in the C++ source files.

• The current version of the project is stored in the VERSION.txt file. For the release, the version must be a plain dotted number such as 0.11.0, without any extra suffixes. Update the file and commit changes to your local branch.

Documentation

• Find the file "release notes" file corresponding to the version being released. It should be in docs/releases/vX.Y.0.rst. Update the .. changelog:: directive to include the version number and the release date. (Note: you would not be able to specify the wheels yet).

• Open file docs/releases/index-releases.rst and update the entry for the version being released.

• In the docs/ folder and run make clean && make html. Ensure that the documentation builds without errors/warnings.

• Open the locally built documentation in the browser and check that it rendered properly. In particular, pay attention to broken links. If necessary, make changes and commit.

• Update the list of contributors in the "release notes" file:

  • First, create a personal access token on github, and put it into environment variable GITHUB_AUTH_TOKEN;
  • Run pip install pygithub --upgrade;
  • Run python ci/gh.py authors --milestone "<milestone name>" --auth;
  • In the release notes documentation file, create section .. contributors:: at the bottom of the page;
  • Paste the output of the script above as the content of the contributors section;
  • Remove line -- PRs -- and replace -- issues -- with --;
  • Rebuild the docs and check that there are no warnings/errors (Note: if there is an unclear sphinx error, then running sphinx-build -P -b html . _build/html may help debug it);
  • Look at the rendered list of contributors: if any person has only github handle and not a name, then check that person's profile and add his/her full name in angle brackets after their username;
  • Commit changes.

• In the docs/start/quick-start.rst update the version of datatable printed to the new version.

• Check the root README.md if it needs to be updated.

Build the release

• Make sure that any pending changes were committed, and push your local rel-X.Y branch to origin. Note that this branch will be automatically protected against deletion by GitHub.

• On GitHub, create a PR from the branch that was just pushed. The PR should be marked as Closes #<current issue>.

• While the PR is building, go into the logs on Jenkins/AppVeyor and verify that the build_info files in the produced wheels have correct (1) version number, (2) .git_revision points to the correct git SHA (tip of rel-X.Y branch), (3) .git_branch contains the name rel-X.Y, (4) .build_mode is "release" (except for debug wheels):

  • py3.8-manylinux-x86_64;
  • py3.9-manylinux-x86_64;
  • py3.10-manylinux-x86_64;
  • py3.11-manylinux-x86_64;
  • py3.12-manylinux-x86_64;
  • py3.8-macosx-x86_64;
  • py3.9-macosx-x86_64;
  • py3.10-macosx-x86_64;
  • py3.11-macosx-x86_64;
  • py3.12-macosx-x86_64;
  • py3.8-win-amd64;
  • py3.9-win-amd64;
  • py3.10-win-amd64;
  • py3.11-win-amd64;

• Merge the PR into main, but DO NOT delete the branch. This branch should be kept forever. (Note: normally the branch should be protected automatically, so you won't be able to delete it).

• Go to https://github.com/h2oai/datatable/branches and verify that the branch is there.

Publish to PyPI

• Download all binaries that were built to a new folder: go to the "Summary" page of the release PR Action page, and download/unpack all artifacts.

  • wheels for macOS;
  • wheels for manylinux;
  • wheels for Windows;
  • source distribution (.tar.gz file).
  • There should be 15 files in total (ls -la datatable-* | wc -l).

• Upload all binaries to PyPI:

  ls datatable-*  # check that there are no any extra files
  twine upload datatable-*

  (you may need to figure out a password. This is left as an exercise for the reader).

• Visit PyPI and verify that the upload was successful.

This is it. At this point the release is officially out.

Publish to GitHub

• Create a new tag on GitHub corresponding to the latest release (you have to be at the top of the rel-0.11 branch when running these commands):

  git tag -a v0.11.0 -m "Release 0.11.0"
  git push origin v0.11.0
  

• Go to Releases page and create a new release. For the tag, select the tag that you just pushed. In the description, provide the link to the Release Notes on the ReadTheDocs website. Make sure to attach all the same binaries as you uploaded to PyPI.

Post-release actions

• Create a new milestone on GitHub, corresponding to the next version that will be released in the future.

• Close the previous milestone (corresponding to the version that was just released).

• Update the VERSION.txt file in main so that it contains the next version number, with suffix a. For example, 1.0.0a. Commit and push to main.

Documentation update

• Switch back to branch rel-X.Y. Open the documentation file docs/releases/v.X.Y.0.rst and list the links to all wheel that were just published on PyPI.

• Rebuild the documentation and verify that everything renders properly.

• Commit and push directly to branch rel-X.Y (however, there is no need to rebuild anything).

• Switch back to main and create a new branch for documentation update. Cherry-pick the PR that you just pushed to rel-X.Y. Use git cherry-pick <SHA> command.

• Create a new release notes file corresponding to the next version to be released: docs/releases/v{NEXTVERSION}.rst. The file should contain an empty .. changelog:: directive.

• Commit, open a PR, and then merge it to main.

• After the PR is merged, go to the ReadTheDocs website and check that the latest version was rebuilt successfully.

• After the previous step, go to Versions page on the same website and "activate" the version corresponding to the new rel-X.Y branch. (This branch will appear in the list after the previous step has finished). The build of that version should trigger automatically.

The End

• Tell someone about the new release. It could be an announcement on Twitter, or in the Slack channel, or wherever. The announcement should normally include a link to the Release Notes on the ReadTheDocs website.

• Close this issue.