Add a Markdown how-to

docs/cli.rst

@@ -27,6 +27,7 @@ Build the combined news file from news fragments.
 
    Only render news fragments to standard output.
    Don't write to files, don't check versions.
+   Only renders the news fragments **without** the surrounding template.
 
 .. option:: --name NAME
 

docs/configuration.rst

@@ -17,11 +17,14 @@ Top level keys
 ~~~~~~~~~~~~~~
 
 - ``directory`` -- If you are not storing your news fragments in your Python package, or aren't using Python, this is the path to where your newsfragments will be put.
-- ``newsfile`` -- The filename of your news file. ``NEWS.rst`` by default.
-- ``package`` -- The package name of your project. (Python projects only)
-- ``package_dir`` -- The folder your package lives. ``./`` by default, some projects might need to use ``src``. (Python projects only)
+- ``filename`` -- The filename of your news file.
+  ``NEWS.rst`` by default.
+- ``package`` -- The package name of your project.
+  (Python projects only)
+- ``package_dir`` -- The folder your package lives. ``./`` by default, some projects might need to use ``src``.
+  (Python projects only)
 - ``template`` -- Path to an alternate template for generating the news file, if you have one.
-- ``start_line`` -- The magic string that ``towncrier`` looks for when considering where the release notes should start.
+- ``start_string`` -- The magic string that ``towncrier`` looks for when considering where the release notes should start.
   ``.. towncrier release notes start`` by default.
 - ``title_format`` -- A format string for the title of your project.
   ``{name} {version} ({project_date})`` by default.

docs/index.rst

@@ -12,6 +12,7 @@ Narrative
    :maxdepth: 1
 
    tutorial
+   keep-a-changelog
 
 
 Reference

docs/keep-a-changelog.rst

@@ -0,0 +1,162 @@
+How to Keep a Changelog in Markdown
+===================================
+
+`Keep a Changelog <https://keepachangelog.com/>`_ is a standardized way to format a news file in `Markdown <https://en.wikipedia.org/wiki/Markdown>`_.
+
+This guide shows you how to configure ``towncrier`` for keeping a Markdown-based news file of a project without using any Python-specific features.
+Everything used here can be use with any other language or platform.
+
+This guide makes the following assumptions:
+
+- The project lives at https://github.com/twisted/my-project/.
+- The news file name is ``CHANGELOG.md``.
+- You store the news fragments in the ``changelog.d`` directory at the root of the project.
+
+Put the following into your ``pyproject.toml`` or ``towncrier.toml``:
+
+.. code-block:: toml
+
+   [tool.towncrier]
+   directory = "changelog.d"
+   filename = "CHANGELOG.md"
+   start_string = "<!-- towncrier release notes start -->\n"
+   underlines = ["", "", ""]
+   template = "changelog.d/changelog_template.jinja"
+   title_format = "## [{version}](https://github.com/twisted/my-project/tree/{version}) - {project_date}"
+   issue_format = "[#{issue}](https://github.com/twisted/my-project/issues/{issue})"
+
+   [tool.towncrier.fragment.security]
+   name = "Security"
+
+   [tool.towncrier.fragment.removed]
+   name = "Removed"
+
+   [tool.towncrier.fragment.deprecated]
+   name = "Deprecated"
+
+   [tool.towncrier.fragment.added]
+   name = "Added"
+
+   [tool.towncrier.fragment.changed]
+   name = "Changed"
+
+   [tool.towncrier.fragment.fixed]
+   name = "Fixed"
+
+
+Next create the news fragment directory and the news file template:
+
+.. code-block:: console
+
+   $ mkdir changelog.d
+
+And put the following into ``changelog.d/changelog_template.jinja``:
+
+.. code-block:: jinja
+
+   {% if sections[""] %}
+   {% for category, val in definitions.items() if category in sections[""] %}
+
+   ### {{ definitions[category]['name'] }}
+
+   {% for text, values in sections[""][category].items() %}
+   - {{ text }} {{ values|join(', ') }}
+   {% endfor %}
+
+   {% endfor %}
+   {% else %}
+   No significant changes.
+
+
+   {% endif %}
+
+
+Next, create the news file with an explanatory header::
+
+   $ cat >CHANGELOG.md <<EOF
+   # Changelog
+
+   All notable changes to this project will be documented in this file.
+
+   The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+   This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/twisted/my-project/tree/main/changelog.d/>.
+
+   <!-- towncrier release notes start -->
+
+
+   EOF
+
+.. note::
+
+   The two empty lines at the end are on purpose.
+
+That's it!
+You can start adding news fragments:
+
+.. code-block:: console
+
+   $ towncrier create -c "Added a cool feature!" 1.added.md
+   $ towncrier create -c "Changed a behavior!" 2.changed.md
+   $ towncrier create -c "Deprecated a module!" 3.deprecated.md
+   $ towncrier create -c "Removed a square feature!" 4.removed.md
+   $ towncrier create -c "Fixed a bug!" 5.fixed.md
+   $ towncrier create -c "Fixed a security issue!" 6.security.md
+   $ towncrier create -c "Fixed a security issue!" 7.security.md
+   $ towncrier create -c "A fix without an issue number!" +something-unique.fixed.md
+
+
+After running ``towncrier build --yes --version 1.0.0`` (you can ignore the Git error messages) your ``CHANGELOG.md`` looks like this:
+
+.. code-block:: markdown
+
+   # Changelog
+
+   All notable changes to this project will be documented in this file.
+
+   The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+   This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/twisted/my-project/tree/main/changelog.d/>.
+
+   <!-- towncrier release notes start -->
+
+   ## [1.0.0](https://github.com/twisted/my-project/tree/1.0.0) - 2022-09-28
+
+
+   ### Added
+
+   - Added a cool feature! [#1](https://github.com/twisted/my-project/issues/1)
+
+
+   ### Changed
+
+   - Changed a behavior! [#2](https://github.com/twisted/my-project/issues/2)
+
+
+   ### Deprecated
+
+   - Deprecated a module! [#3](https://github.com/twisted/my-project/issues/3)
+
+
+   ### Fixed
+
+   - Fixed a bug! [#5](https://github.com/twisted/my-project/issues/5)
+   - A fix without an issue number!
+
+
+   ### Removed
+
+   - Removed a square feature! [#4](https://github.com/twisted/my-project/issues/4)
+
+
+   ### Security
+
+   - Fixed a security issue! [#6](https://github.com/twisted/my-project/issues/6), [#7](https://github.com/twisted/my-project/issues/7)
+
+
+Pretty close, so this concludes this guide!
+
+.. note::
+
+   - Because ``towncrier`` doesn't have a concept of a "previous version" (yet), the version links will point to the release tags and not to the ``compare`` link like in *Keep a Changelog*.
+   - *Keep a Changelog* doesn't have the concept of a uncategorized change, so the template doesn't expect any.

src/towncrier/newsfragments/436.doc

@@ -0,0 +1 @@
+Added a Markdown-based how-to guide.