From f3e0db42518e7b78640f5692f4da186e65754be3 Mon Sep 17 00:00:00 2001 From: Marcos Dione Date: Tue, 7 May 2024 11:44:13 +0200 Subject: [PATCH 1/5] Attempt to makethese paragraphs more clear. --- docs/how-to/contribute/code.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/how-to/contribute/code.rst b/docs/how-to/contribute/code.rst index 84ea2b56df..7af516fab6 100644 --- a/docs/how-to/contribute/code.rst +++ b/docs/how-to/contribute/code.rst @@ -895,16 +895,29 @@ The corresponding change note would read something like: Date widgets can now accept US-style MM-DD-YYYY format. -See `News Fragments -`__ -for more details on the types of news fragments you can add. You can also see -existing examples of news fragments in the ``changes/`` folder. Name the file -using the number of the issue that your pull request is addressing. When there +The filename has to follow this format: + + [ID].[fragmet_type].rst + +The ID can be either the issue number or the pull request number. When there isn't an existing issue, you can create the pull request in two passes: First submit it without a change note - this will fail, but will also assign a pull request number. You can then push an update to the pull request, adding the change note with the assigned number. +The five default fragment types are: + +- ``feature``: Signifying a new feature. +- ``bugfix``: Signifying a bug fix. +- ``doc``: Signifying a documentation improvement. +- ``removal``: Signifying a deprecation or removal of public API. +- ``misc``: A ticket has been closed, but it is not of interest to users. + +For more informatin see `News Fragments +`__, + +You can also see existing examples of news fragments in the ``changes/`` folder. + It's not just about coverage! ----------------------------- From 46b98006f80d6c9c913e3a550847c2617a25a811 Mon Sep 17 00:00:00 2001 From: Marcos Dione Date: Tue, 7 May 2024 11:59:31 +0200 Subject: [PATCH 2/5] Formatting. --- docs/how-to/contribute/code.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/how-to/contribute/code.rst b/docs/how-to/contribute/code.rst index 7af516fab6..a2b1338d41 100644 --- a/docs/how-to/contribute/code.rst +++ b/docs/how-to/contribute/code.rst @@ -895,9 +895,7 @@ The corresponding change note would read something like: Date widgets can now accept US-style MM-DD-YYYY format. -The filename has to follow this format: - - [ID].[fragmet_type].rst +The filename has to follow this format: ``[ID].[fragmet_type].rst`` The ID can be either the issue number or the pull request number. When there isn't an existing issue, you can create the pull request in two passes: First @@ -913,7 +911,7 @@ The five default fragment types are: - ``removal``: Signifying a deprecation or removal of public API. - ``misc``: A ticket has been closed, but it is not of interest to users. -For more informatin see `News Fragments +For more information about fragment types see `News Fragments `__, You can also see existing examples of news fragments in the ``changes/`` folder. From 56e84b5fca7ee44932f1c82430aef5c703f9bb61 Mon Sep 17 00:00:00 2001 From: Marcos Dione Date: Tue, 7 May 2024 12:02:53 +0200 Subject: [PATCH 3/5] Explain empty changes directory. --- docs/how-to/contribute/code.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/how-to/contribute/code.rst b/docs/how-to/contribute/code.rst index a2b1338d41..f6b871070a 100644 --- a/docs/how-to/contribute/code.rst +++ b/docs/how-to/contribute/code.rst @@ -914,7 +914,9 @@ The five default fragment types are: For more information about fragment types see `News Fragments `__, -You can also see existing examples of news fragments in the ``changes/`` folder. +You can also see existing examples of news fragments in the ``changes/`` folder. +If the folder is empty, it's because it's cleaned up on every release. +Try some commit before the release itself. It's not just about coverage! ----------------------------- From 8b90ef4d1dffca4ebb6f1d5486c4b2a9f6592a79 Mon Sep 17 00:00:00 2001 From: Marcos Dione Date: Sat, 11 May 2024 15:16:40 +0200 Subject: [PATCH 4/5] Create 2565.doc.rst --- changes/2565.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/2565.doc.rst diff --git a/changes/2565.doc.rst b/changes/2565.doc.rst new file mode 100644 index 0000000000..c78f0af7ec --- /dev/null +++ b/changes/2565.doc.rst @@ -0,0 +1 @@ +Expanded the text a little about files in the `changes/` directory so it's more explicit. From 63c91703747f5587d778f31a9d100828f53da6f8 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sun, 12 May 2024 13:35:23 +0800 Subject: [PATCH 5/5] Fixed some typos and reworked some explanations. --- changes/2565.doc.rst | 2 +- docs/how-to/contribute/code.rst | 83 +++++++++++++++++++++------------ 2 files changed, 53 insertions(+), 32 deletions(-) diff --git a/changes/2565.doc.rst b/changes/2565.doc.rst index c78f0af7ec..ba0515e571 100644 --- a/changes/2565.doc.rst +++ b/changes/2565.doc.rst @@ -1 +1 @@ -Expanded the text a little about files in the `changes/` directory so it's more explicit. +The instructions for adding a changenote to a pull request have been clarified. diff --git a/docs/how-to/contribute/code.rst b/docs/how-to/contribute/code.rst index f6b871070a..1026aed7dd 100644 --- a/docs/how-to/contribute/code.rst +++ b/docs/how-to/contribute/code.rst @@ -876,18 +876,18 @@ Commit your changes to this branch, then push to GitHub and create a pull reques Add change information for release notes ---------------------------------------- -Before you submit this change as a pull request, you need to add a *change note*. -Toga uses `towncrier `__ to -automate building release notes. To support this, every pull request needs to -have a corresponding file in the ``changes/`` directory that provides a short -description of the change implemented by the pull request. +Before you submit this change as a pull request, you need to add a *change +note*. Toga uses `towncrier `__ to automate +building the release notes for each release. Every pull request must include at +least one file in the ``changes/`` directory that provides a short description +of the change implemented by the pull request. This description should be a high level summary of the change from the perspective of the user, not a deep technical description or implementation -detail. It is distinct from a commit message - a commit message describes -what has been done so that future developers can follow the reasoning for -a change; the change note is a "user facing" description. For example, if -you fix a bug caused by date handling, the commit message might read: +detail. It is distinct from a commit message - a commit message describes what +has been done so that future developers can follow the reasoning for a change; +the change note is a "user facing" description. For example, if you fix a bug +caused by date handling, the commit message might read: Modified date validation to accept US-style MM-DD-YYYY format. @@ -895,28 +895,49 @@ The corresponding change note would read something like: Date widgets can now accept US-style MM-DD-YYYY format. -The filename has to follow this format: ``[ID].[fragmet_type].rst`` - -The ID can be either the issue number or the pull request number. When there -isn't an existing issue, you can create the pull request in two passes: First -submit it without a change note - this will fail, but will also assign a pull -request number. You can then push an update to the pull request, adding the -change note with the assigned number. - -The five default fragment types are: - -- ``feature``: Signifying a new feature. -- ``bugfix``: Signifying a bug fix. -- ``doc``: Signifying a documentation improvement. -- ``removal``: Signifying a deprecation or removal of public API. -- ``misc``: A ticket has been closed, but it is not of interest to users. - -For more information about fragment types see `News Fragments -`__, - -You can also see existing examples of news fragments in the ``changes/`` folder. -If the folder is empty, it's because it's cleaned up on every release. -Try some commit before the release itself. +The change note should be in ReST format, in a file that has name of the format +``..rst``. If the change you are proposing will fix a bug or +implement a feature for which there is an existing issue number, the ID will be +the number of that ticket. If the change has no corresponding issue, the PR +number can be used as the ID. You won't know this PR number until you push the +pull request, so the first CI pass will fail the Towncrier check; add the change +note and push a PR update and CI should then pass. + +There are five allowed fragment types: + +- ``feature``: The PR adds a new behavior or capability that wasn't previously + possible (e.g., adding a new widget, or adding a significant capability to an + existing widget); +- ``bugfix``: The PR fixes a bug in the existing implementation; +- ``doc``: The PR is an significant improvement to documentation; +- ``removal``; The PR represents a backwards incompatible change in the Toga + API; or +- ``misc``; A minor or administrative change (e.g., fixing a typo, a minor + language clarification, or updating a dependency version) that doesn't need to + be announced in the release notes. + +Some PRs will introduce multiple features and fix multiple bugs, or introduce +multiple backwards incompatible changes. In that case, the PR may have multiple +change note files. If you need to associate two fragment types with the same ID, +you can append a numerical suffix. For example, if PR 789 added a feature +described by ticket 123, closed a bug described by ticket 234, and also made two +backwards incompatible changes, you might have 4 change note files: + +* ``123.feature.rst`` +* ``234.bugfix.rst`` +* ``789.removal.1.rst`` +* ``789.removal.2.rst`` + +For more information about Towncrier and fragment types see `News Fragments +`__. +You can also see existing examples of news fragments in the ``changes`` +directory of the Toga repository. If this folder is empty, it's likely because +Toga has recently published a new release; change note files are deleted and +combined to update the :doc:`release notes ` with +each release. You can look at that file to see the style of comment that is +required; you can look at `recently merged PRs +`__ to see how to +format your change notes. It's not just about coverage! -----------------------------