Development Release

Hartmut Goebel edited this page Jan 15, 2017 · 9 revisions

This page describes the release process for PyInstaller.

Version Scheme

Regarding version scheme, PyInstaller conforms to PEP440. The Version scheme looks like:

N.N[.N][.devN][+commit[.mod]]

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 this description, list pypitest first. This will make zest.releaser push the release there first giving you a chance for last minute fixes.

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. Recompile the binary bootloaders for every supported OS (Win/Lin/OSX) and commit them. You may want to use the Vagrantfile accompanying the bootloader sources to build for other platforms.

    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

    • ask you a few questions - required version, ...
    • remove .devN from the version string
    • update date and version in doc/CHANGES.rst
  4. Rebuild the man-pages and commit them:

    make PYINSTALLER_DO_RELEASE=1 -C doc/ man
    git commit -m "Rebuild man-pages for release $version" doc/
    
  5. Update ``doc/CHANGES.rst`` and ``doc/CREDITS.rst``.

    Where to look for possible changes? You can look in pull requests, issues, commits, mailing list or even PyInstaller cli options (new/removed options).

    Credits should be updated based on merged pull requests.

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

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

      git commit -m "Update CHANGES and CREDITS for release $version" doc/
      
  6. In the README, update the URLs for the manual to point to pythonhosted.org, the versions in the badge-images and related links:

    scripts/update-readme-versions.sh $version
    
    1. Verify the result be running:

      git diff --color-words='.' README.rst
      
    2. 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
      
    3. If everything is fine, commit:

      git commit -m 'Update versions in README.' README.rst
      README_CHANGE=$(git rev-parse --short HEAD) # remember this commit
      
  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 "Finished 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 "Finished release $version."
      
    1. Tag and sign the release (we are using prefix v):

      git tag -s v$version -m "PyInstaller $version"
      
  9. Run the release script release and it will do:

    • create another (unsigned) 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!

  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.

    3. Copy there changelog for the current release. This should look like this one

    4. 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 <https://readthedocs.org/dashboard/pyinstaller/versions/> verify that the new release tag as marked as "active".

  13. Add a new version-label 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 master
    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 "Finished release $version." 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