From fef668afecde6bb386b51587fcaae00210e8ccad Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Wed, 28 Sep 2022 19:45:23 +0200
Subject: [PATCH] Un-deprecate array-style custom fragments

---
 docs/configuration.rst              | 44 +++++++++++++++++++++++++++++
 src/towncrier/newsfragments/438.doc |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 src/towncrier/newsfragments/438.doc

diff --git a/docs/configuration.rst b/docs/configuration.rst
index 06bfb6ec..160ad60e 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -36,6 +36,12 @@ Custom fragment types
 ``towncrier`` allows defining custom fragment types.
 Custom fragment types will be used instead ``towncrier`` default ones, they are not combined.
 
+There are two ways to add custom fragment types.
+
+
+Defining Custom Fragment Types With a TOML Mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Users can configure each of their own custom fragment types by adding tables to
 the pyproject.toml named ``[tool.towncrier.fragment.<a custom fragment type>]``.
 
@@ -59,6 +65,44 @@ For example, if you want your custom fragment types to be ``["feat", "fix", "cho
    showcontent = false
 
 
+.. warning::
+
+   Since TOML mappings aren't ordered, the sections are always rendered alphabetically.
+
+
+Defining Custom Fragment Types With an Array of TOML Tables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can create their own custom fragment types by adding an array of
+tables to the pyproject.toml named ``[[tool.towncrier.type]]``.
+
+If you use this way to configure custom fragment types, please note that ``fragment_types`` must be empty or not provided.
+
+Each custom type (``[[tool.towncrier.type]]``) has the following
+mandatory keys:
+
+* ``directory``: The type / category of the fragment.
+* ``name``: The description of the fragment type, as it must be included
+  in the news file.
+* ``showcontent``: Whether if the fragment contents should be included in the
+  news file.
+
+For example:
+
+.. code-block:: toml
+
+   [tool.towncrier]
+   [[tool.towncrier.type]]
+   directory = "deprecation"
+   name = "Deprecations"
+   showcontent = true
+
+   [[tool.towncrier.type]]
+   directory = "chore"
+   name = "Other Tasks"
+   showcontent = false
+
+
 All Options
 -----------
 
diff --git a/src/towncrier/newsfragments/438.doc b/src/towncrier/newsfragments/438.doc
new file mode 100644
index 00000000..92785dba
--- /dev/null
+++ b/src/towncrier/newsfragments/438.doc
@@ -0,0 +1 @@
+Defining custom fragments using a TOML array is not deprecated anymore.