README.rst
1Hear ye, hear ye, says the ``towncrier``
2========================================
3
4.. image:: https://travis-ci.org/hawkowl/towncrier.svg?branch=master
5 :target: https://travis-ci.org/hawkowl/towncrier
6
7.. image:: https://codecov.io/github/hawkowl/towncrier/coverage.svg?branch=master
8 :target: https://codecov.io/github/hawkowl/towncrier?branch=master
9
10``towncrier`` is a utility to produce useful, summarised news files for your project.
11Rather than reading the Git history as some newer tools to produce it, or having one single file which developers all write to, ``towncrier`` reads "news fragments" which contain information `useful to end users`.
12
13Philosophy
14----------
15
16``towncrier`` delivers the news which is convenient to those that hear it, not those that write it.
17
18That is, by duplicating what has changed from the "developer log" (which may contain complex information about the original issue, how it was fixed, who authored the fix, and who reviewed the fix) into a "news fragment" (a small file containing just enough information to be useful to end users), ``towncrier`` can produce a digest of the changes which is valuable to those who may wish to use the software.
19These fragments are also commonly called "topfiles" or "newsfiles" in Twisted parlance.
20
21``towncrier`` works best in a development system where all merges involve closing a ticket.
22
23
24Quick Start
25-----------
26
27Install from PyPI::
28
29 python3 -m pip install towncrier
30
31.. note::
32
33 ``towncrier``, as a command line tool, works on Python 3.5+ only.
34 It is usable by projects written in other languages, provided you give it the version of the project when invoking it.
35 For Python 2/3 compatible projects, the version can be discovered automatically.
36
37In your project root, add a ``pyproject.toml`` file, with the contents::
38
39 [tool.towncrier]
40 package = "mypackage"
41 package_dir = "src"
42 filename = "NEWS.rst"
43
44Then put news fragments (see "News Fragments" below) into a "newsfragments" directory under your package (so, if your project is named "myproject", and it's kept under ``src``, your newsfragments dir would be ``src/myproject/newsfragments/``).
45
46To prevent git from removing the newsfragments directory, make a ``.gitignore`` file in it with::
47
48 !.gitignore
49
50This will keep the folder around, but otherwise "empty".
51
52``towncrier`` needs to know what version your project is, and there are two ways you can give it:
53
54- For Python 2/3 compatible projects, a ``__version__`` in the top level package.
55 This can be either a string literal, a tuple, or an `Incremental <https://github.com/hawkowl/incremental>`_ version.
56- Manually passing ``--version=<myversionhere>`` when interacting with ``towncrier``.
57
58To produce a draft of the news file, run::
59
60 towncrier --draft
61
62To produce the news file for real, run::
63
64 towncrier
65
66This command will remove the news files (with ``git rm``) and append the built news to the filename specified in ``towncrier.ini``, and then stage the news file changes (with ``git add``).
67It leaves committing the changes up to the user.
68
69If you wish to have content at the top of the news file (for example, to say where you can find the tickets), put your text above a rST comment that says::
70
71 .. towncrier release notes start
72
73``towncrier`` will then put the version notes after this comment, and leave your existing content that was above it where it is.
74
75
76News Fragments
77--------------
78
79``towncrier`` has a few standard types of news fragments, signified by the file extension.
80These are:
81
82- ``.feature``: Signifying a new feature.
83- ``.bugfix``: Signifying a bug fix.
84- ``.doc``: Signifying a documentation improvement.
85- ``.removal``: Signifying a deprecation or removal of public API.
86- ``.misc``: A ticket has been closed, but it is not of interest to users.
87
88The start of the filename is the ticket number, and the content is what will end up in the news file.
89For example, if ticket #850 is about adding a new widget, the filename would be ``myproject/newsfragments/850.feature`` and the content would be ``myproject.widget has been added``.
90
