[docs] Multiple issues per fragment

[jamescw19]

The builder issue sorting code and the default template section item values suggest that it's possible to have multiple issues per each fragment.
Looking through the source code and the docs, it's not clear how a fragment could end up with more than one issue number. Parsing a fragment only uses the previous file part and there's no splitting or grouping that happens later, but by the time this gets passed to the template, issues are wrapped in a list.

Is this an intended upcoming feature? If not, the comments/template/builder code should be changed as there's no need to keep fragment issues as a list if there can only be one issue.

[jamescw19]

After a bit more searching, I can now see this grouping happens by fragment content here. Some comment/documentation should be added to reflect that this is possible and this is how towncrier groups issue numbers.

[frankkusters]

After a bit more searching, I can now see this grouping happens by fragment content here. Some comment/documentation should be added to reflect that this is possible and this is how towncrier groups issue numbers.

For anyone in 2023, here's an updated link:

towncrier/src/towncrier/_builder.py

Line 173 in ab08d55

texts[content] = sorted(texts[content] + [ticket])

[adiroiban]

I don't think I understand the use case from here.

An example with a set of input files and expected output together with the actual output would help a lot.

We are happy to receive PR for documentation improvements.
The source code is open so anyone should be able to check the code and update the documentation :)

Thanks

[jamescw19]

It would have helped if I'd used permalinks (issue now edited), so I'll update the links to show the issue.
At the time, this comment was in the render_fragments section. This shows a fragment linked to 3 issues as - Fix the thing (#7, #123, #2). My question was around how this would be created with fragment files, if possible at all:

Option 1, allow multiple issues in the file title:

1.2.3.feature
This is a feature 
-> This is a feature (#1, #2, #3)

Option 2, match fragments based on their contents:

1.feature
This is a feature 
2.feature
This is a feature
3.feature
This is a feature
-> This is a feature (#1, #2, #3)

Or Option 3, don't support this at all and remove the example in the comments/output template.

I'll be honest, I haven't kept up to date with this repo in the past year so this may have been implemented or the comment changed. If so, feel free to close.

[adiroiban]

Ah, I see.

So the input is a file name "231.462.212.feature" and this means that this features "closes/is associated" with ticket 231 and 462 and 212 while the text is the same

I have never found this use case.

It happens that when working on a branch for example for 231.feature, it happens that it also fixes "462.feature" and "212.bugfix" but each fragment has a separate text.

To, me, having the exact same text for multiple tickets makes no sense :)

It means that those tickets are duplicate... and 2 of them should be closed as duplicate , and keep only one.

Or if they are not duplicates, they should have separate text...in separate files.

---

The docs are now hosted at https://towncrier.readthedocs.io/en/stable/

I can see this documented here as Option 2 https://towncrier.readthedocs.io/en/stable/tutorial.html#creating-news-fragments

$ towncrier create --content 'Can also be ``rst`` as well!' 3456.doc.rst
# You can associate multiple ticket numbers with a news fragment by giving them the same contents.
$ towncrier create --content 'Can also be ``rst`` as well!' 7890.doc.rst

---

Are you saying this is a bug, and it doesn't work as documented?

An actual example or steps to reproduce it would help.

This is what I get on trunk (Option 2)

$ echo "Some content" > src/towncrier/newsfragments/123.feature
$ echo "Some content" > src/towncrier/newsfragments/125.feature
$ git add src/towncrier/newsfragments/

$ towncrier --draft
Loading template...
Finding news fragments...
Rendering news fragments...
Draft only -- nothing has been written.
What is seen below is what would be written.

towncrier 23.6.1.dev0 (2023-07-07)
==================================

Features
--------

- Some content (`#123 <https://github.com/twisted/towncrier/issues/123>`_, `#125 <https://github.com/twisted/towncrier/issues/125>`_)


Deprecations and Removals
-------------------------

- The support for Python 3.7 has been dropped. (`#521 <https://github.com/twisted/towncrier/issues/521>`_)


Misc
----

- `#520 <https://github.com/twisted/towncrier/issues/520>`_, `#522 <https://github.com/twisted/towncrier/issues/522>`_, `#523 <https://github.com/twisted/towncrier/issues/523>`_

[hynek]

I personally would find this useful (I hate fixing a typo in three files), but I would suggest to use commas to make it a bit more idiomatic: 123,456,789.feature looks more like a list, especially if you use file type suffixes like I do 123,456,789.feature.md

[jamescw19]

@adiroiban Thanks for clarifying the current behaviour - I suspect this didn't work when I opened the issue in 2021. It was more about documenting the behaviour, and as this has been documented and works as expected, I'm happy to close (or re-focus) this issue.

To, me, having the exact same text for multiple tickets makes no sense :)

To be clear, it's not the original tickets that have duplicate text, but the news fragment content.
You're right in principle that there shouldn't be duplication, and that changes should address one issue only. But, I've found it happens in practice that a single small change can close (or, invalidate) a separate issue. Alternatively, it can be useful to associate fragments with larger implications to multiple issues.

Given this is currently possible with duplication, it feels like a nice-to-have to consolidate duplicates into a single file. The format @hynek suggests seems best to me (and shows it's not just me who attaches multiple issues to a fragment :) )

[adiroiban]

To be clear, it's not the original tickets that have duplicate text, but the news fragment content.
You're right in principle that there shouldn't be duplication, and that changes should address one issue only. But, I've found it happens in practice that a single small change can close (or, invalidate) a separate issue. Alternatively, it can be useful to associate fragments with larger implications to multiple issues.

It's still not clear :)

If I am in feature branch targeting ticket 123 and it also fixes 234 and 456 I do someting like this:

$ echo "Description for 123 feature." > src/towncrier/newsfragments/123.feature
$ echo "Text about how 234 was fixed." > src/towncrier/newsfragments/234.bugfix
$ echo "456 is just tech debt." > src/towncrier/newsfragments/456.misc

In a branch, you can add as many fragments as you like :)

I think that this can be closed...since we sort of have documentation for this :)

Feel free to add more comments to this ticket and we can reopen if the documentation is not good enough.

[SmileyChris]

I also agree it's dirty relying on the actual fragment content to group issues and that hynek's suggestion would be a better way (even if we keep the current behaviour for backwards compatibility). This ticket is specifically about the documentation of it, and we do have the feature (and it's documented) already even if it could be better. so I'm closing.

I'll open a new ticket for the idea of having multiple issues in the fragment filename.