Refactor issue_key function to sort issues in a human-friendly way #608

SmileyChris · 2024-06-05T03:29:54Z

Description

In the issue key sorting method, there's this comment:

        # Maybe we should sniff strings like "gh-10" -> (10, "gh-10")?

Let's do that.

To be more backwards compatible, we'll continue putting just plain numbers last. In reality, it's very unlikely a project is mixing issue types, but if they are, then they'll be grouped:

>>> sorted(["2", "#11", "#3", "gh-10", "gh-4", "omega", "alpha"], key=issue_key)
['alpha', 'omega', '#3', '#11', 'gh-4', 'gh-10', '2']

Checklist

Make sure changes are covered by existing or new tests.
For at least one Python version, make sure local test run is green.
Create a file in src/towncrier/newsfragments/. Describe your
change and include important information. Your change will be included in the public release notes.
Make sure all GitHub Actions checks are green (they are automatically checking all of the above).

for more information, see https://pre-commit.ci

…rted

adiroiban

Thanks! Looks good. Only minor comments.

src/towncrier/test/test_builder.py

src/towncrier/newsfragments/608.feature.rst

src/towncrier/_builder.py

Co-authored-by: Adi Roiban <adiroiban@gmail.com>

src/towncrier/newsfragments/608.feature.rst

src/towncrier/test/test_builder.py

adiroiban · 2024-06-10T08:59:25Z

src/towncrier/test/test_builder.py

+
+    def test_ordering(self):
+        """
+        Issues are ordered first by the non-text component, then by their number.


I guess here "issues" means "news fragments"

Suggested change

Issues are ordered first by the non-text component, then by their number.

News fragments are ordered first by the non-text component, then by their number.

src/towncrier/test/test_builder.py

src/towncrier/newsfragments/608.feature.rst

src/towncrier/_builder.py

adiroiban

Thanks for the update.

I left a few inline comments.

I think that part of my confusion is the use of the term "issue" in this PR.

I am not sure what an "issue" is: news fragment vs ticket ID

I think it helps to use consistent terminolgy across the code base and the documentation.

I am not a big fan of "news fragment" ... but this is what we have and I think that we should continue to use it.

Thanks again!

Co-authored-by: Adi Roiban <adiroiban@gmail.com>

for more information, see https://pre-commit.ci

SmileyChris · 2024-06-13T04:55:12Z

I am not sure what an "issue" is: news fragment vs ticket ID

@adiroiban I actually decided to switch to issue rather than ticket. My logic is it's the only term actually used in code and changing it for consistency would be backwards incompatible.

We use the issue_format configuration option and the issues_by_category context argument when rendering.

Even though it's not your preference, are you ok with using "issue" across the board instead of ticket?

adiroiban · 2024-06-13T09:21:55Z

Thanks for the update

Even though it's not your preference, are you ok with using "issue" across the board instead of ticket?

Sure. No problem.

Your suggestion is much bettter.

Happy to see some improvements here

Thanks

adiroiban

Thanks for the update. All good!

…wisted#608) * Refactor issue_key function to sort issues in a human-friendly way * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Rename newsfragment * Small improvement to test to show how text with numeric issues are sorted * Update src/towncrier/_builder.py docstring grammar Co-authored-by: Adi Roiban <adiroiban@gmail.com> * clarify new behaviour in newsfragment * Add some docstrings/comments to tests * linelength fix * Clarify news fragments vs tickets Co-authored-by: Adi Roiban <adiroiban@gmail.com> * Consistent use of "issue" rather than "ticket" * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * typo --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Adi Roiban <adiroiban@gmail.com>

* Always content for orphans, since they don't have a concept of tickets * Add tests for orphans in non showcontent categories * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Add newsfragment * Add a note in the configuration docs about the change to orphan fragments in non-showcontent categories * Use rst admonitions for the showcontent notes * Refactor rendering of title via `config.title_format` (#610) * Refactor rendering of title via config.title_format * Add newsfragment * Config docs * Fix restructuredtext formatting error * Refactor issue_key function to sort issues in a human-friendly way (#608) * Refactor issue_key function to sort issues in a human-friendly way * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Rename newsfragment * Small improvement to test to show how text with numeric issues are sorted * Update src/towncrier/_builder.py docstring grammar Co-authored-by: Adi Roiban <adiroiban@gmail.com> * clarify new behaviour in newsfragment * Add some docstrings/comments to tests * linelength fix * Clarify news fragments vs tickets Co-authored-by: Adi Roiban <adiroiban@gmail.com> * Consistent use of "issue" rather than "ticket" * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * typo --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Adi Roiban <adiroiban@gmail.com> * variable now called issue instead of ticket --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Adi Roiban <adiroiban@gmail.com>

Refactor issue_key function to sort issues in a human-friendly way

2fe403a

SmileyChris requested a review from a team as a code owner June 5, 2024 03:29

pre-commit-ci bot and others added 4 commits June 5, 2024 03:30

[pre-commit.ci] auto fixes from pre-commit.com hooks

8f1d692

for more information, see https://pre-commit.ci

Rename newsfragment

88555d4

Merge remote-tracking branch 'upstream/trunk' into Better-issue-sorting

08e4281

Small improvement to test to show how text with numeric issues are so…

989ed4e

…rted

adiroiban approved these changes Jun 5, 2024

View reviewed changes

src/towncrier/test/test_builder.py Outdated Show resolved Hide resolved

src/towncrier/test/test_builder.py Outdated Show resolved Hide resolved

src/towncrier/newsfragments/608.feature.rst Outdated Show resolved Hide resolved

src/towncrier/_builder.py Outdated Show resolved Hide resolved

SmileyChris and others added 3 commits June 10, 2024 10:29

Update src/towncrier/_builder.py docstring grammar

081af67

Co-authored-by: Adi Roiban <adiroiban@gmail.com>

clarify new behaviour in newsfragment

b39dd8a

Add some docstrings/comments to tests

5931717

SmileyChris requested a review from adiroiban June 9, 2024 22:50

linelength fix

ed811ff

SmileyChris commented Jun 9, 2024

View reviewed changes

src/towncrier/newsfragments/608.feature.rst Show resolved Hide resolved