From 58e81952e37c80fe7c0a5db6750d7079e1017bbf Mon Sep 17 00:00:00 2001 From: Harendra Kumar Date: Thu, 1 Nov 2018 01:24:58 +0530 Subject: [PATCH] Add pull request checklists --- CONTRIBUTING.md | 73 +++++++++++++++++++++++++++++++++++++------------ MAINTAINING.md | 27 ++++++++++++------ 2 files changed, 74 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0927b5414..c01118636 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,26 +9,53 @@ we will appreciate if you provide as much detail as possible to reproduce or understand the problem, but nevertheless you are encouraged to open an issue for any problem that you may encounter. -## Developer documentation - -Build haddock with the `--show-all` option to see the documentation for all -modules including the ones not exposed to users of the library. -For example, -`stack haddock --haddock-arguments "--show-all" --no-haddock-deps`. - ## Pull Requests (PR) Please feel free to [send a pull -request (PR)](https://github.com/composewell/streamly/pulls) whether it is a single -letter typo fix in documentation or a more complex change. If the feature makes -significant changes to design, we encourage you to open an issue as early as -possible so that you do not have to redo much work because of changes in design -decisions. However, if you are confident, you can still go ahead and take that -risk. +request (PR)](https://github.com/composewell/streamly/pulls) whether it is a +single letter typo fix or a complex change. We will accept any PR that makes a +net positive change to the package. We encourage you to provide a complete, +consistent change with test, documentation and benchmarks. You can contact the +[maintainers](https://gitter.im/composewell/streamly) for any help or +collaboration needed in that regard. However, if due to lack of time you are +not able to complete the PR, you are still welcome to submit it, maintainers +will try their best to actively contribute and pick up your change as long as +the change is approved. + +## Pull Request (PR) Checklist + +Here is a quick checklist for a PR, for details please see the next section: + +* PR contains one logical changeset +* Each commit in the PR consists of a logical change +* Commits are rebased/squashed/fixup/reordered as needed +* Stylistic changes to irrelevant parts of the code are separated in + independent commits. +* Code is formatted as per the style of the file or that of other files +* Compiler warnings are fixed +* Reasonable hlint suggestions are accepted +* Tests are added to cover the changed parts +* All [tests](test) pass +* [Performance benchmarks](benchmark) are added, where applicable +* No significant regressions are reported by [performance benchmarks](benchmark/README.md) +* Haddock documentation is added to user visible APIs and data types +* Tutorial module, [README](README.md), and [guides](docs) are updated if + necessary. +* [Changelog](Changelog.md) is updated if needed + +## Contributing A Change + +If the feature makes significant changes to design, we encourage you to open an +issue as early as possible so that you do not have to redo much work because of +changes in design decisions. However, if you are confident, you can still go +ahead and take that risk as the maintainers are supposed to be reasonable +people. ### Picking Issues to Work on -Beginners are encouraged to pick up issues that are marked `help wanted`. +Beginners are encouraged to pick up issues that are marked `help wanted`. It is +a good idea to update the issue expressing your intent so that others do not +duplicate the effort and people with a background on the issue can help. ### Changeset in a PR @@ -60,13 +87,16 @@ BRANCH. ### Testing -It is a good idea to include tests for the changes where applicable. +It is a good idea to include tests for the changes where applicable. See the +existing tests [here](test). ### Documentation For user visible APIs, it is a good idea to provide haddock documentation that is easily understood by the end programmer and does not sound highfalutin, -and preferably with examples. +and preferably with examples. If your change affects the tutorial or needs to +be mentioned in the tutorial then please update the tutorial. Check if the +additional [guides](docs) are affected or need to updated. ### Performance Benchmarks @@ -75,8 +105,8 @@ any of the existing performance benchmarks. If you introduced something new then you may want to add benchmarks to check if it performs as well as expected by the programmers to deem it usable. -See the README file in the `benchmark` directory for more details on how to run -the benchmarks. +See the [README](benchmark/README) file in the `benchmark` directory for more +details on how to run the benchmarks. ### Changelog @@ -99,6 +129,13 @@ of the library please indicate that in the `Changelog` as `Breaking Changes` and also write short notes regarding what the programmers need to do to adapt their existing code to the new change. +## Developer documentation + +Build haddock with the `--show-all` option to see the documentation for all +modules including the ones not exposed to users of the library. +For example, +`stack haddock --haddock-arguments "--show-all" --no-haddock-deps`. + ## Coding ### Style diff --git a/MAINTAINING.md b/MAINTAINING.md index 96ff46774..f45788c64 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -1,5 +1,16 @@ # Maintainers' Guide +## PR Merge Checklist + +* All the CI tests pass +* New tests are added where applicable +* Benchmarks are added where applicable +* hlint +* Run benchmarks locally if you suspect any regressions +* If the PR is by someone other than you yourself then merge with a merge + commit, otherwise merge by rebasing on master without a separate merge + commit. + ## Release Checklist * Check if any critical pending bugs or issues are to be included @@ -50,11 +61,11 @@ * Check haddocks on Hackage, upload if not built * Announce to haskell-cafe@haskell.org -## Issue Labels +## Managing Issues ### User Impacting Changes -__RULE__ Any commit that may affect the end user in some way MUST have either a +__RULE__: Any commit that may affect the end user in some way MUST have either a changelog entry OR MUST have an issue marked with one of the following labels OR both. We can have more than one of these labels on the same issue e.g. breaking, enhancement: @@ -78,11 +89,12 @@ changelog entry or an issue. Issues that do not have a corresponding commit may be left without a label but preferably should be marked with one of the following: -* invalid * question -* wontfix +* discussion * maintenance * testing +* invalid +* wontfix ### Feature Labels @@ -93,10 +105,9 @@ group the issues together. * help wanted * duplicate +* deferred -## Managing Changes - -### Planning and Tracking Changes +## Correlating Changes, Issues and Releases For planning purposes, open issues may be marked with milestones or target releases. However, it may not always be known which release a fix will finally @@ -121,7 +132,7 @@ following: release that affects the end user, especially bugs and breaking changes MUST have the target release correctly set. -### Changelog Management +## Changelog Management Keep the unreleased changes in the `Unreleased` section at the top of changelog file. Using `Unreleased` instead of the next release number for unreleased