Development Release

Hartmut Goebel edited this page Sep 9, 2018 · 17 revisions

This page describes the release process for PyInstaller.

Version Scheme

PyInstaller conforms to the PEP440 version scheme, which looks like: N.N[.N][.devN][+commit[.mod]]. Some examples:

  • Releases: 3.0, 3.0.1, 3.1, 3.1.1
  • Prereleases: 3.0.dev0, 3.0.1.dev1
  • Source code from git: 3.1.1.dev0+9d0e0ad
  • Source code from git with local modifications: 3.1.1.dev0+9d0e0ad.mod

Preparation

  1. Get yourself an account at PyPI and TestPyPI. Fill both credentials in your ~/.pypirc file, as described in the Python Wiki.
    • In difference to that description, list pypitest first. This will make zest.releaser push the release there first, giving you a chance for last minute fixes.
  2. Generate yourself a GnuPG/PGP key (if you do not have one already). Please search the internet for one of the many tutorials on how to generate a new GnuGP key.
  1. Install the requirements listed in tests/requirements-developer.txt. You may want to use a virtual environment (and activate it).

Doing a Prerelease

Prerelease is useful if you want to publish PyInstaller to PyPI for testing. This prereleases might be installed by users. This command will install latest prerelease available on PyPI: pip install --pre PyInstaller`.

  • Run the following script. It will asks you a few questions. It also creates git tag, tarball and uploads tarball to PyPI:

    ./scripts/do_release
    
  • Increment devN version number in file ./PyInstaller/__init__.py. For example 3.0.dev6 -> 3.0.dev7

  • Commit the changed version.

  • Push new version and new prerelease git tag to github:

    git push --follow-tags
    
  • Download source archives from PyInstaller at PyPI and append it to github release page.

Full Release Process

  1. Prepare (see above).

  2. Implement and close all issues and pull requests in a specific milestone.

  3. Ensure everything relevant is committed and tested. git stash your local changes which should not go into the release.

  4. If necessary, recompile the binary bootloaders for every supported OS and commit them.

    1. To learn if it is necessary to recompile the bootloaders you may use:

      git log --oneline -- bootloader/ PyInstaller/bootloader/
      
    2. You may want to use the Vagrantfile accompanying the bootloader sources to build for other platforms. Have a look at the bootloader/build.sh for details.

    3. Push to github.

  5. Continuous integration tests should pass.

Now we start with the main release process.

  1. Set a shell variable to be able to copy-and-paste the remaining snippets, e.g.:

    version=3.1
    
  2. Create the release branch:

    git checkout -b release/$version
    
  3. Update versions in Source-code, Changelog, etc.:

    prerelease # zest.releaser command
    

    This will

    • run some checks,
    • ask you a few questions - required version, ...
    • remove .devN from the version string
    • update date, version and changes (from towncrier) in doc/CHANGES.rst
  4. Update ``doc/CHANGES.rst`` and ``doc/CREDITS.rst``.

    Review CHANGES.rst` to ensure all relevant changes are mentioned. Sort and clean up the entries.

    Credits should be updated based on merged pull requests.

    1. Check if the files are valid reStructuredText by running:

      make -C doc/ html
      xdg-open doc/_build/html/CHANGES.html  # opens file in your web-browser
      
    1. If everything is fine, commit:

      git commit --amend doc/CHANGES.rst -C ORIG_HEAD git commit -m "Update CREDITS for release $version" doc/CREDITS.rst

  5. In the README, update the URLs to include the current version and verify the result:

    scripts/update-readme-versions.sh $version
    git diff --color-words='.' README.rst
    
    1. Again, check if the files are valid reStructuredText by running:

      rst2html README.rst > /tmp/README.html
      xdg-open /tmp/README.html  # opens file in your web-browser
      
    2. If everything is fine, commit:

      git commit -m 'Update versions in README.' README.rst
      README_CHANGE=$(git rev-parse --short HEAD) # remember this commit
      
  6. Rebuild the man-pages and commit them:

    make PYINSTALLER_DO_RELEASE=1 -C doc/ man git commit -m "Doc: Rebuild man-pages for release $version" doc/

  7. Adjust whatever else is required for the release now.

  8. Complete the release:

    1. Merge into branch master:

      git checkout master
      git merge --no-ff -m "Release $version." release/$version
      
    2. In case of a merge-conflict, resolve it using:

      git gui # In the context-menu select "Use Local Version"
      git commit -m "Release $version."
      
  9. Run the release script release and it will do:

    • create a signed tag for the released version
    • create and sign source archives
    • uploads them to PyPI
    release # zest.releaser command
    
    Note: Due to a bug in zest.releaser, the .asc will not be uploaded.

    For now you need to run twine yourself like this:

    cd /tmp/PyInstaller-v$version-*/gitclone/dist
    twine upload -r testpypi --sign PyInstaller-$version*.{whl,tar.gz}*
    twine upload --sign PyInstaller-$version*.{whl,tar.gz}*
    

    Submit to testpypi first! You can not change any file after you've uploaded it to PyPI!

  10. Push the changes:

    git push --follow-tags origin master
    
  11. Create release on github:

    1. Go to the PyInstaller tags page

    2. Edit the latest tag details. Just point to the Changelog in the manual:

      See https://pyinstaller.readthedocs.io/en/vVERSION/CHANGES.html for Changelog.
      
    3. Upload the .tar.gz- and .zip-archives and GPG-signatures that where uploaded to PyInstaller at PyPI

      Note: If you are using stuff like RequestBlocker or NoScript in your web-browser, mind to allow some additional access.

  12. At readthedocs verify that the new release tag as marked as "active". If the current tag is missing, manually rebuild "latest" on the Builds page.

  13. At Github add a new version-label (like v3.3) for issues with color-code #ededed at https://github.com/pyinstaller/pyinstaller/labels

  14. Update the website, the wiki, and check the FAQ.

  15. Announce the new release on:

Now we are going to perform some post-release steps:

  1. Checkout the release-branch and forward it to master:

    git checkout release/$version
    git reset --hard master
    
  2. Revert the version-related to the README (using the commit we remembered earlier):

    git revert --no-edit $README_CHANGE
    
  3. Run the release script postrelease:

    postrelease # zest.releaser command
    

    This will

    • increment version string for a new release: 3.0 -> 3.1.dev0
    • prepare doc/CHANGES.rst for the next release.
  4. Merge into branch develop:

    git checkout develop
    git merge --no-ff -m "Merge release $version into develop." release/$version
    
  5. Check the diffs: it should only be version related stuff:

    git diff origin/develop
    
  6. Push the changes and delete the local release branch:

    git push --follow-tags origin develop master
    git branch -d release/$version
    

Hotfix Release Process

1.-5: see above

  1. Set an shell variable to be able to copy-and-paste the remaining snippets, e.g.:

    based_on=3.1
    version=3.1.1
    
  2. Create the release branch:

    git checkout -b release/$version v$based_on
    
  3. Run the release script postrelease (yes, post), to prepare doc/CHANGES.rst for the next release:

    postrelease # NO NOT COMMIT!
    prerelease # Now commit
    
  4. Normally there is no need to rebuild the manual.

  1. Complete the release:

    1. Merge into branch master:

      git checkout master
      git merge --no-ff -m "Finished release $version." release/$version
      
  2. Run the release script release and it will do:

    • create another tag for the released version
    • create and sign source archives and uploads them to PyPI
    release # zest.releaser command
    git tag -d $version  # delete the additional tag
    

    Submit to testpypi first! You can not change any file after you've uploaded it to PyPI!

Now we are going to perform some post-release steps:

You are still on the release-branch :-)

  1. Revert the version-related to the README:

    git revert ...
    
  2. Run the release script postrelease:

    postrelease # zest.releaser command
    

    This will

    • increment version string for a new release: 3.0 -> 3.1.dev0
    • prepare doc/CHANGES.rst for the next release.
  3. Merge into branch develop:

    git checkout develop
    git merge --no-ff -m "Finished release $version." release/$version
    

    In case of merge-conflicts resolve everything to "Local version", except of doc/CHANGES and doc/CREDITS.

  4. Check the diffs: it should only be version related stuff:

    git diff origin/develop
    
  5. Push the changes:

    git push origin develop
    
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.