Building Releases
=================

Roundup is a pure Python application with no binary components. This file
describes how to build a source release. To find out how to install
Roundup, read the doc/installation.txt file.

Roundup release checklist:

1.  Regenerate locale/roundup.pot.  See "Extracting Translatable
    Messages" in doc/developers.txt.  This is best done some time in
    advance of the release to allow for translators to update their
    translations. Merge into .po files by running 'make *.po'
    in the locale directory. Run:

       make template
       make *.po

2.  Run unit tests! They should pass successfully. Install pytest
    using pip2/pip3 for python2 and python3. Then invoke pytest
    using both python versions from the top of the roundup tree:

        python3 -m pytest test/
        python2 -m pytest test/

3.  Update version in:
      CHANGES.txt
      roundup/__init__.py
      website/www/index.txt
      website/www/conf.py  (also update copyright)
3a. Update license end date in COPYING.txt
3b. Update doc/acknowledgements.txt (add section for
    release, churn contributers etc.). (Use hg churn -c -r ####..####)
4.  Update documentation
      doc/announcement.txt
      doc/upgrading.txt
4a. cd to website/www and run 'make linkcheck'. See output in
    _tmp/linkcheck/output.txt
       fix broken references in docs
       verify redirects are correct
5.  Update setup.py info if needed (contacts, classifiers, etc.). When
    releasing check that Development Status matches release: stable,
    beta alpha etc.

    Check that metadata is valid and long descriptions is proper reST:

      python setup.py check --restructuredtext --metadata --strict
   
6.  Clean out all *.orig, *.rej, .#* files from the source.

      find . -name '*.orig' -exec rm {} \;
      find . -name '*.rej' -exec rm {} \;
      find . -name '.#*' -exec rm {} \;

6a. Rebuild .mo translation files in distribution

      cd locale
      make
      cd ..

7.  Remove previous build files

      python setup.py clean --all
      rm -rf build/share  # deletes locale .mo files

    Build including new .mo files built in 6a.

      python setup.py build

    (sdist generation will fail if this isn't done)
8.  Rebuild documentation in "share/doc/roundup/html"

      python setup.py build_doc

9.  Generate source distribution:

      python setup.py sdist

    (if you find sdist a little verbose, add "--quiet" to the end of the
     command)
9a. 2021/04/17 skip this for now. Need to make sure that whl installs
    exectuable scripts properly and update these directions to test.

       python2 setup.py bdist_wheel; python3 setup.py bdist_wheel

    to create binary distributions in wheel format. (egg format is
    deprecated.)
10. Check the roundup.egg-info/SOURCES.txt to make sure that any new files are
    included.  (use hg status --rev <last release or tag>:tip to list changed
    added and removed files. Last release e.g. 1.5.1 where tip is what would
    become 1.6) E.G.
      
      hg status --rev 1.5.1:tip | sed -ne 's/^A //p' | while read i ; \
      do echo $i; grep "$i" roundup.egg-info/SOURCES.txt; done | uniq -c

    Anything with a count of 1 is not in the manifest.
    If there are missing files that should be in the manifest,
    edit MANIFEST.in to include them. For format docs see
    https://packaging.python.org/guides/using-manifest-in/#using-manifest-in
    (Note: files under website/ shouldn't be in the manifest.)
11. Unpack the new tarball created in dist/roundup-<version>.tar.gz
    file in /tmp then
      a) run tests using installed pytest run under python2 and
         python3. (python2 -m pytest test/; python3 -m pytest test/)
      b) demo.py
    with all available Python versions.
11a. (TBD how to test wheel binary distribution before uploading.)
12. Assuming all is well tag the release in the version-control
    system.
      a) hg tag 1.6.0  # use right version. Should create/commit a changeset
      b) hg push       # update main repo
      c) hg sum        # verify that the tag shows up
13. Upload source distribution to PyPI - requires you sign up for a
    pypi account and be added as a maintainer to roundup. Ask existing
    maintainer for access. You can do this two ways:

      python setup.py sdist upload --repository pypi --sign

    which rebuilds the source distribution tarball and uploads it.
    This means that you have uploaded something tha is not tested. It
    should be the same as the tarball you tested but....

    Another way to do this is to use twine (pip install twine).
    You need to sign the tarball. This can be done with:

      cd dist
      gpg --detach-sign --armor <filename>.tgz
      
    you should be prompted to use the roundup release key. If not you
    can add  --local=roundup-devel@lists.sourceforge.net.
    This will create a file by the name <filename>.tgz.asc. Then
    use twine to upload *both* the asc and distibution tarball
    at the same time. E.G.:x

       twine upload --repository pypi <filename>.tar.gz <filename>.tar.gz.asc

    (If you upload the .asc file separately from the distibution file
    it gets a different path and is not able to be located in the pypi
    interface. The asc file is downloaded using the tarball path and
    add `asc'.)

    The distribution file should appear on
    https://pypi.python.org/pypi/roundup in no time. If you are using
    python older than 2.7.13 you need a .pypirc shown below since the
    URL has changed. If using 2.7.13 or newer, you can remove the
    "--repository pypi" option and use 'setup.py sdist upload...'.

    You can also use twine to upload the .whl (wheel) format
    distributions (if created). Follow the directions for generating
    the gpg asc files and upload the .whl distribution and .whl.asc
    signature files together.
14. Send doc/announcement.txt to python-announce@python.org and
    roundup-users@lists.sourceforge.net and
    roundup-devel@lists.sourceforge.net
14b. Update entry on https://freshcode.club/projects/roundup-tracker
14c. Update entries for fossies by emailing announcement to
     announce@fossies.org
15. Refresh website.
      website/README.txt
      https://www.roundup-tracker.org/ should state that the stable
      version is the one that you released.
      https://www.roundup-tracker.org/docs.html should also match the
      released version (or at least the major non pre-release
      1.x/2.x version).

-------------

If you get errors on the upload operation, you may need the following
~/.pypirc file as well

========
[distutils]
index-servers =
    test
    pypi

[pypi]
repository: https://upload.pypi.org/legacy/
username: <your username on pypi.org here>
password: <your password here>

[test]
repository: https://test.pypi.org/legacy/
username: <your username on test.pypi.org here>
password: <your password here>
========