File	Date	Author	Commit
doc	2021-11-26	Florent Rougon	[52f4ec] Home page: switch to the new https-based URL
examples	2021-06-19	Florent Rougon	[b28378] demo: add example of an msgbox with timeout
.gitattributes	2014-10-15	Florent Rougon	[130399] Release 3.2.0
.gitignore	2019-11-30	Florent Rougon	[88a3f0] Switch the packaging from Distutils to Setuptools
AUTHORS	2013-08-16	Florent Rougon	[dcfe3a] Prepare for the 2.12 release
COPYING	2009-10-30	Florent Rougon	[83a024] Import version 2.08
COPYING.Sphinx	2014-10-15	Sphinx team	[603665] Add the Makefile generated by sphinx-quickstart
ChangeLog.init	2021-06-19	Florent Rougon	[90ffae] Update ChangeLog.init (improve some log messages)
INSTALL	2019-12-14	Florent Rougon	[46fb68] Safer instruction when using easy_install
MANIFEST.in	2016-05-07	Florent Rougon	[8c93c4] Prune doc/screenshots/snapshots.debian.net when...
README.distributors	2019-11-30	Florent Rougon	[88a3f0] Switch the packaging from Distutils to Setuptools
README.rst	2021-11-26	Florent Rougon	[9ff791] Release 3.5.3
TODO	2014-08-19	Florent Rougon	[4370bb] Miscellaneous little changes to ancillary files
dialog.py	2021-11-26	Florent Rougon	[9ff791] Release 3.5.3
setup.cfg	2019-11-30	Florent Rougon	[88a3f0] Switch the packaging from Distutils to Setuptools
setup.py	2021-11-26	Florent Rougon	[52f4ec] Home page: switch to the new https-based URL

Read Me

-*- coding: utf-8 -*-

Packaging from a release tarball
================================

Packaging from an official release tarball ("source distribution" in
PyPA-speak[1]) should be fairly straightforward, as every source
distribution should contain a ChangeLog file that is ready to use. The rest of
this file mainly concerns developers and people wanting to package
pythondialog from a clone of the Git repository.

[1] https://packaging.python.org/glossary/#term-source-distribution-or-sdist


Management of the ChangeLog file
================================

Starting from version 2.14.1, the ChangeLog file is not part of the Git
repository anymore, because it is automatically generated from the Git log
with the gitlog-to-changelog[2] program. But it must be present in every
released tarball or package!

  [2] https://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob_plain;f=build-aux/gitlog-to-changelog

To make this as easy as possible, setup.py does the following:
  - create or refresh (overwriting) ChangeLog from ChangeLog.init and the Git
    log if there is a .git subdirectory in the current directory. This is very
    quick and done every time setup.py is run. For this to work,
    gitlog-to-changelog must be in the PATH and executable.
  - use the existing ChangeLog file if there is no .git subdirectory (this is
    for people building from a release tarball as opposed to a clone of the
    Git repository);
  - include the ChangeLog file in every source distribution made with
    "setup.py sdist".


Packaging from a clone of the Git repository
============================================

If you want to prepare a package from a clone of the Git repository, you
should:

  - make sure the 'version_info' variable towards the top of dialog.py
    indicates a Git snapshot, with something like:

      version_info = VersionInfo(2, 14, 1, ".git20130930")

  - install gitlog-to-changelog (single-file Perl script, see above for the
    download location) and make sure setup.py can find it. Unless you modify
    setup.py, this means you have to make it executable and put it somewhere
    in your PATH. You may have to replace the first lines of shell+Perl crap
    with a proper shebang line (such as "#! /usr/bin/perl"). You can run
    'gitlog-to-changelog --help' to check that it is working.

  - run 'setup.py sdist' to generate the ChangeLog and prepare a source
    distribution. Alternatively, if you only want to generate the ChangeLog,
    you can use a command such as the following, which writes its output in
    the UTF-8 encoding:

      python3 -c \
   'import setup; setup.generate_changelog("ChangeLog", write_to_stdout=True)' \
   >/path/to/generated/ChangeLog

    If you want to do some testing of the command by piping the output into
    a pager such as less, don't forget to type Ctrl-L to refresh the initial
    screen, because it may be garbled due to the messages sent to stderr
    (alternatively, you can redirect stderr).