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. "./run_tests.py"
3.  Update version
      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.
6a. Rebuild .mo translation files in distribution - cd locale; make
7.  Remove previous build files
      python setup.py clean --all
      rm -rf build/share  # deletes locale .mo files
    Rebuild and install .mo files
      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.  python setup.py sdist --manifest-only
10. Check the MANIFEST 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 was
      what would become 1.6) E.G.
      
      hg status --rev 1.6.0:tip | sed -ne 's/^A //p' | while read i ; \
      do echo $i; grep "$i" MANIFEST; 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
    http://docs.python.org/2/distutils/sourcedist.html#manifest-template
    (Notes files for the website and issue tracker shouldn't be in the
    manifest.)
11. python setup.py sdist
    (if you find sdist a little verbose, add "--quiet" to the end of the
     command)
12. Unpack the new tarball created in dist/roundup-<version>.tar.gz
    file in /tmp then
      a) run_tests.py
      b) demo.py
    with all available Python versions.
13. 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
14. 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.
      python setup.py sdist upload --repository pypi --sign
    It should appear on http://pypi.python.org/pypi/roundup in no
    time. If you are using python older than 2.7.13 you need a
    .pypirc shown below. URL has changed. If using 2.7.13 or newer,
    you can remove the "--repository pypi" option.
15. Send doc/announcement.txt to python-announce@python.org and
    roundup-users@lists.sourceforge.net and
    roundup-devel@lists.sourceforge.net
15b. Update entry on https://freshcode.club/projects/roundup-tracker
15c. Update entries for fossies by emailing announcement to
     announce@fossies.org
16. 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).

So, those commands in a nice, cut'n'pasteable form::

 find . -name '*.orig' -exec rm {} \;
 find . -name '*.rej' -exec rm {} \;
 find . -name '.#*' -exec rm {} \;
 python setup.py clean --all
 python setup.py build
 python setup.py check --restructuredtext --metadata --strict
 python setup.py build_doc
 cd locale
 make
 cd ..
 python setup.py sdist --manifest-only
 python setup.py sdist --quiet
 ## python setup.py bdist_rpm
 # not required for pypi.org since 2017 -> python setup.py register
 python setup.py sdist upload --repository pypi --sign

Note pypi no longer allows uploads of .exe installers such as produced
by bdist_wininst. Removed directions for producing the binary
distribution.

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>
========