From 56a68462b25f865940757d880e55ab03d67093b7 Mon Sep 17 00:00:00 2001 From: Rebecca Turner Date: Mon, 25 Nov 2024 11:52:17 -0800 Subject: [PATCH] PR template: Make it better! The new PR template is short and sweet! - PR templates will be read many times. PR authors will NOT see Markdown links rendered, so they add a lot of visual noise. Most links are therefore removed. - There's a balance here: A lot of these checks have additional detail in the CONTRIBUTING.md. Linking to a section can be helpful for new contributors, but if their eyes glaze over the whole item after deeming it too noisy, the CONTRIBUTING.md serves no benefit. - Most of the checks are pretty self-explanatory, so hopefully this is OK. - Added checks for items that are listed in the "other conventions" but are handy to have explicitly: Haddocks are added, changelog entries are written, etc. - Unified the two checklists; now, authors just have to decide if each check is relevant for their PR, rather than reading qualifications for which checklist to use. - Would it be worth splitting the CONTRIBUTING.md up or publishing developer documentation explicitly? See the Rustc developer guide for a model: https://rustc-dev-guide.rust-lang.org/ --- .github/pull_request_template.md | 34 +++++++++++--------------------- 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e6576b7d92d..ce0692d6761 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,25 +1,15 @@ -Please read [Github PR Conventions](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#github-pull-request-conventions) and then fill in *one* of these two templates. + -Include the following checklist in your PR: - -* [ ] Patches conform to the [coding conventions](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#other-conventions). -* [ ] Any changes that could be relevant to users [have been recorded in the changelog](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#changelog). - * [ ] [Is the change significant?](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#is-my-change-significant) If so, remember to add `significance: significant` in the changelog file. -* [ ] The documentation has been updated, if necessary. -* [ ] [Manual QA notes](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#qa-notes) have been included. -* [ ] Tests have been added. (*Ask for help if you don’t know how to write them! Ask for an exemption if tests are too complex for too little coverage!*) - ---- - -**Template B: This PR does not modify behaviour or interface** - -*E.g. the PR only touches documentation or tests, does refactorings, etc.* - -Include the following checklist in your PR: - -* [ ] Patches conform to the [coding conventions](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#other-conventions). -* [ ] Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions). +- [ ] Tests have been added (Ask for help if you don’t know how to write them) + - [ ] Manual QA notes have been added +- [ ] A changelog entry has been added in `changelog.d/pr-YOUR_PR_NUMBER` +- [ ] Documentation has been updated +- [ ] Haddock comments for new top-level definitions have been added +- [ ] `base` and third-party library imports use qualified imports or explicit import lists +- [ ] Commit messages are formatted nicely +- [ ] Post-merge: Backports for older Cabal release branches have been created