diff --git a/.changelog/2697.internal.md b/.changelog/2697.internal.md new file mode 100644 index 00000000000..48ff83a006d --- /dev/null +++ b/.changelog/2697.internal.md @@ -0,0 +1,4 @@ +changelog: Reference multiple issues/pull requests for a single entry + +For more details, see the description in [Change Log fragments]( +.changelog/README.md#multiple-issues--pull-requests-for-a-single-fragment). diff --git a/.changelog/README.md b/.changelog/README.md index 7f25a638910..c90ec216f71 100644 --- a/.changelog/README.md +++ b/.changelog/README.md @@ -83,6 +83,27 @@ Example file names: - `3456.bugfix.1.md`, - `3456.bugfix.2.md`. +## Multiple issues / pull requests for a single fragment + +Sometimes referencing multiple issues or pull requests in a Change Log +fragment is desired. + +For example: + +- when a single Change Log fragment describes a change that resolves multiple + issues, or +- when a sub-sequent issue / pull request augments a change that already has a + corresponding Change Log fragment. + +In this case, you need to augment (if necessary) the original Change Log +fragment (e.g. `1234.feature.md`) and copy it to a new file which has the new +issue or pull request number in its name (e.g. `1356.feature.md`). +The [towncrier] tool will automatically detect a duplicate Change Log fragment +and combine issue / pull request numbers in a single Change Log entry. + +_NOTE: You can repeat this process to refer to as many issues / pull requests +as needed._ + ## Render Change Log preview To get a preview of how your change (and other changes queued up in this diff --git a/.changelog/template.md.j2 b/.changelog/template.md.j2 index ea49fe71187..dc95d7defd0 100644 --- a/.changelog/template.md.j2 +++ b/.changelog/template.md.j2 @@ -9,14 +9,15 @@ {% for text, values in sections[section][category].items() %} {% set lines = text.splitlines() %} +{% set referenced_issues = "(" + values | join(',\n ') + ")" %} {% if lines | length > 2 and lines[1] == "" %} - {{ lines[0] }} - ({{ values | join(', ') }}) + {{ referenced_issues }} {{ lines[2:] | join('\n') }} {% else %} - {{ text }} - ({{ values | join(', ') }}) + {{ referenced_issues }} {% endif %} {% if not loop.last %}