Wendelin Home Wendelin

    Wendelin.core - Release howto

    This howto documents wendelin.core release procedure. It also applies to other Python software, for example to zodbtools and pygolang.
    • Last Update:2020-10-14
    • Version:002
    • Language:en

    Wendelin.core - Release Howto

    Author: Kirill Smelkov <kirr@nexedi.com>
    Date: 2015 June 16
    last-updated-for:
     wendelin.core v0.3

    Abstract

    This document describes steps needed to make a new release of wendelin.core

    Make worktree clean

    Either

    1. make sure your working tree is clean:

      $ git clean -fdX
      $ git submodule foreach git clean -fdX
      

      or

    2. clone wendelin.core afresh:

      $ git clone --recursive https://lab.nexedi.com/nexedi/wendelin.core
      $ cd wendelin.core
      
    Increase version & describe changes
    1. Increment version in setup.py .
    2. Describe what has been changed in this release in CHANGES.
    Make sure it works

    Run set-up tox tests. This will test whether wendelin.core builds ok with various python versions and various ZODB versions:

    $ tox
    

    tail of output should be something like:

    ...
    ________ summary ________
    py27-ZODB3: commands succeeded
    py27-ZODB4: commands succeeded
    py34-ZODB4: commands succeeded
    congratulations :)
    

    Note

    if you experience failures, while running tox, e.g. code crashes saying zodbpickle module is not found, before running tests, make sure your tox/virtualenv is uptodate.

    e.g. on Debian system:

    $ virtualenv venv-4release
    $ . venv-4release/bin/activate
    $ pip install tox
    $ hash -r
    
    Make release commit
    1. Ensure to stage changes in setup.py and CHANGES for commit. E.g. with:

      $ git add -p
      ( interactively select changes to commit )
      
    2. Ensure all changes were staged and there will be no other changes in worktree after commit:

      $ git status
      ( should be absent or empty section "Changes not staged for commit:" )
      
    3. Make release commit:

      $ git commit -S -m "wendelin.core vX.y"
      
    4. Make release tag:

      $ git tag -s -m "wendelin.core vX.y"  vX.y
      

    Note

    The commit and tag are made gpg-signed (the -S and -s options)

    Prepare release tarball
    $ python setup.py sdist
    

    this should create dist/wendelin.core-X.y.tar.gz .

    Check restructured text syntax
    $ twine check dist/*
    

    this checks that the syntax of the long description is written in a syntaxically correct restructured text and will render properly on pypi.

    It's also a good idea to use a spellchecker to detect English mistakes.

    Test release tarball

    Unpack intended-to-release tarball somewhere and test it again with tox:

    $ mkdir tmp
    $ cd tmp
    $ tar xfz ../dist/wendelin.core-X.y.tar.gz
    $ cd wendelin.core-X.y
    $ tox
    

    The output should be again:

    ...
    ________ summary ________
    py27-ZODB3: commands succeeded
    py27-ZODB4: commands succeeded
    py34-ZODB4: commands succeeded
    congratulations :)
    

    Warning

    If not:

    1. investigate what is wrong / what needs to be corrected.

    2. remove release tag and commit:

      $ git tag -d vX.y
      $ git reset HEAD~         # keeping made changes to setup.py & CHANGES
      
    3. fix problems; go again to Make release commit.

    Sign release tarball

    If release tarball was tested ok - sign it:

    $ gpg --armor --detach-sign wendelin.core-X.y.tar.gz
    
    Upload to PyPI

    After release tarball is ready and signed - upload it to PyPI:

    $ twine upload -u <your-pypi-account> wendelin.core-X.y.tar.gz*
    

    Warning

    Do not use PyPI web UI to upload new release. The UI has bugs which will prevent uploading this release further even with twine or setup.py upload.

    after uploading, make sure that

    1. sha512sum shown on PyPI corresponds to real sha512sum of dist/wendelin.core-X.y.tar.gz .
    2. PGP signature shown on PyPI is the same as dist/wendelin.core-X.y.tar.gz.asc . Note that currently PyPI does not directly display the signature in the web interface, but it's possible to download the .asc by appending .asc to the tarball download URL .
    Push release commit & tag to public git repo
    $ git push origin master vX.y
    
    Make release announcement (optional for now)

    Tell the world - send email about new release to corresponding mailing lists, LWN.net, etc . Make announcements on twitter and facebook.