From 2908a62d15843597d6ab1dae9cb06ab39dafa3c3 Mon Sep 17 00:00:00 2001 From: Chris Beaven Date: Sat, 27 Apr 2024 00:30:36 +1200 Subject: [PATCH] Add docs for CLI orphan fragments (#589) * Add docs for CLI orphan fragments Refs #584 * Add newsfragment * Mention orphan fragments in doc * Add a note about '+' to the create command's docstring --- docs/cli.rst | 7 +++++++ src/towncrier/create.py | 3 +++ src/towncrier/newsfragments/589.doc | 1 + 3 files changed, 11 insertions(+) create mode 100644 src/towncrier/newsfragments/589.doc diff --git a/docs/cli.rst b/docs/cli.rst index 7af5a3ac..d2fa0d4b 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -79,6 +79,13 @@ If the fragments directory does not exist, it will be created. If the filename exists already, ``towncrier create`` will add (and then increment) a number after the fragment type until it finds a filename that does not exist yet. In the above example, it will generate ``123.bugfix.1.rst`` if ``123.bugfix.rst`` already exists. +To create a news fragment not tied to a specific issue (which towncrier calls an "orphan fragment"), start the fragment name with a ``+``. +If that is the entire fragment name, a random hash will be added for you:: + + $ towncrier create +.feature.rst + $ ls newsfragments/ + +fcc4dc7b.feature.rst + .. option:: --content, -c CONTENT A string to use for content. diff --git a/src/towncrier/create.py b/src/towncrier/create.py index 5242e124..de264121 100644 --- a/src/towncrier/create.py +++ b/src/towncrier/create.py @@ -64,6 +64,9 @@ def _main( * .doc - a documentation improvement, * .removal - a deprecation or removal of public API, * .misc - a ticket has been closed, but it is not of interest to users. + + If the FILENAME base is just '+' (to create a fragment not tied to an + issue), it will be appended with a random hex string. """ __main(ctx, directory, config, filename, edit, content) diff --git a/src/towncrier/newsfragments/589.doc b/src/towncrier/newsfragments/589.doc new file mode 100644 index 00000000..3664626f --- /dev/null +++ b/src/towncrier/newsfragments/589.doc @@ -0,0 +1 @@ +Add docs to explain how ``towncrier create +.feature.rst`` (orphan fragments) works.