From 42b94f5066071d222f164aece888aadc85e4b54e Mon Sep 17 00:00:00 2001 From: Maximilian Tagher Date: Thu, 2 Nov 2017 20:16:33 -0700 Subject: [PATCH 1/3] Add Github issue and PR templates, plus contributing guidelines * Closes #1450 --- .github/ISSUE_TEMPLATE.md | 29 ++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 14 ++++++++ CONTRIBUTING.md | 58 ++++++++++++++++++++++++++++++++ 3 files changed, 101 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..b788b8ca --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,29 @@ + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..c9839a31 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,14 @@ +Before submitting your PR, check that you've: + +- [ ] Bumped the version number +- [ ] Documented new APIs with [Haddock markup](https://www.haskell.org/haddock/doc/html/index.html) +- [ ] Added [`@since` declarations](http://haskell-haddock.readthedocs.io/en/latest/markup.html#since) to the Haddock + +After submitting your PR: + +- [ ] Update the Changelog.md file with a link to your PR +- [ ] Check that CI passes (or if it fails, for reasons unrelated to your change, like CI timeouts) + + \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..cfa95b02 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing + +Thanks for your interest in contributing to Yesod! This file has some tips for developing Yesod and getting a pull request accepted. + +## Development + +Yesod is a mega-repo that contains many Haskell packages, each in a different directory. All the subprojects can be developed with Stack, using `stack `, e.g. + +* `stack build yesod-form` +* `stack test yesod-auth` +* `stack haddock yesod-websockets` + +If you'd like to test your changes in a full-fledged Yesod app, you can use Stack to build against it, e.g.: + +``` +packages: +- '/path/to/this/repo/yesod-auth' +``` + +## Testing + +Tests are appreciated, but not required, for changes to Yesod. + +## Documentation + +All public APIs must be documented. Documenting private functions is optional, but may be nice depending on their complexity. Example documentation: + +``` +-- | Looks up the hidden input named "_token" and adds its value to the params. +-- +-- ==== __Examples__ +-- +-- > request $ do +-- > addToken_ "#formID" +-- +-- @since 1.5.4 +addToken_ :: Query -- ^ CSS selector that resolves to the @
@ containing the token. + -> RequestBuilder site () +``` + +Examples are appreciated, but not required, in documentation. Marking new APIs with `@since ` is required. + +## Versioning + +Yesod packages roughly follow the Haskell Package Versioning Policy, MAJOR.MAJOR.MINOR.PATCH + +* MAJOR - Used for massive changes in the library +* MAJOR - Used for smaller breaking changes, like removing functions or changed behavior of a function. +* MINOR - Used for new public APIs +* PATCH - Used for bug fixes and documentationc changes. + +If you feel there is ambiguity to a change (e.g. fixing a bug in a function, when people may be relying on the old broken behavior), you can ask in an issue or pull request. + +Unlike in the Package Versioning Policy, deprecations are not counted as MAJOR changes. + +## Changelog + +After you submit a PR, update the subproject's Changelog.md file with a link to your PR From 7a4b2812c150dedb4a4350634bf45d8d5b04bd10 Mon Sep 17 00:00:00 2001 From: Maximilian Tagher Date: Wed, 8 Nov 2017 22:32:15 -0800 Subject: [PATCH 2/3] Update contributing guidelines based of Snoyberg's "How to Send Me a PR" post --- CONTRIBUTING.md | 56 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 46 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfa95b02..6914fa00 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,11 +17,39 @@ packages: - '/path/to/this/repo/yesod-auth' ``` -## Testing +## Coding Guidelines -Tests are appreciated, but not required, for changes to Yesod. +### Safety -## Documentation +Avoid partial functions. Even if you know the partial function is safe in your instance, partial functions require more reasoning from the programmer and are not resilient to refactoring. For the rare cases where a partial function is appropriate, a custom `error` should be used. + +### Style + +Keep coding style consistent with the rest of the file, but don't worry about style too much otherwise. PRs changing code style are viewed skeptically. + +### Dependencies + +Avoid adding unnecessary dependencies. If a dependency provides only a minor convenience for your implementation, it's probably better to skip it. + +If you do add a new dependency, try to support a wide range of versions of it. + +### Backwards Compatibility + +Backwards incompatible changes are viewed skeptically—best to ask in an issue to see if a particular backwards incompatible change would be approved. If possible keep backwards compatibility by adding new APIs and deprecating old ones. + +Keep backwards compatibility with old versions of dependencies when possible. + +## PR Guidelines + +### PR Scope + +As much as possible, keep separate changes in separate PRs. + +### Testing + +Tests are recommended, but not required. + +### Documentation All public APIs must be documented. Documenting private functions is optional, but may be nice depending on their complexity. Example documentation: @@ -38,21 +66,29 @@ addToken_ :: Query -- ^ CSS selector that resolves to the @@ containing th -> RequestBuilder site () ``` -Examples are appreciated, but not required, in documentation. Marking new APIs with `@since ` is required. +Examples are recommended, but not required, in documentation. Marking new APIs with `@since ` is required. -## Versioning +### Versioning -Yesod packages roughly follow the Haskell Package Versioning Policy, MAJOR.MAJOR.MINOR.PATCH +Yesod packages roughly follow the Haskell Package Versioning Policy style of MAJOR.MAJOR.MINOR.PATCH * MAJOR - Used for massive changes in the library -* MAJOR - Used for smaller breaking changes, like removing functions or changed behavior of a function. +* MAJOR - Used for smaller breaking changes, like removing, renaming, or changing behavior of existing public API. * MINOR - Used for new public APIs -* PATCH - Used for bug fixes and documentationc changes. +* PATCH - Used for bug fixes + +Documentation changes don't require a new version. If you feel there is ambiguity to a change (e.g. fixing a bug in a function, when people may be relying on the old broken behavior), you can ask in an issue or pull request. Unlike in the Package Versioning Policy, deprecations are not counted as MAJOR changes. -## Changelog +In some cases, dropping compatibility with a major version of a dependency (e.g. changing from transformers >= 0.3 to transformers >= 0.4), is considered a MAJOR breaking change. -After you submit a PR, update the subproject's Changelog.md file with a link to your PR +### Changelog + +After you submit a PR, update the subproject's Changelog.md file with the new version number and a link to your PR. If your PR does not need to bump the version number, include the change in an "Unreleased" section at the top. + +### Releases + +Releases should be done as soon as possible after a pull request is merged—don't be shy about reminding us to make a release if we forget. \ No newline at end of file From 3247237c444d9eeba7de812b29be2c11c1c27663 Mon Sep 17 00:00:00 2001 From: Maximilian Tagher Date: Wed, 8 Nov 2017 22:43:51 -0800 Subject: [PATCH 3/3] Respond to @psibi's comments --- .github/ISSUE_TEMPLATE.md | 2 +- CONTRIBUTING.md | 13 +++++++------ 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index b788b8ca..33b1bfd5 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -25,5 +25,5 @@ command -v yesod && yesod version ### Support -Please direct support questions to [Stack Overflow](https://stackoverflow.com/questions/tagged/yesod) or the [Yesod Google Group](https://groups.google.com/forum/#!forum/yesodweb). If you don't get a response there, or you suspect there may be a bug in Yesod causing your problem, you're welcome to ask here. +Please direct support questions to [Stack Overflow](https://stackoverflow.com/questions/tagged/yesod+haskell) or the [Yesod Google Group](https://groups.google.com/forum/#!forum/yesodweb). If you don't get a response there, or you suspect there may be a bug in Yesod causing your problem, you're welcome to ask here. --> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6914fa00..1b04caf8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,12 +70,13 @@ Examples are recommended, but not required, in documentation. Marking new APIs w ### Versioning -Yesod packages roughly follow the Haskell Package Versioning Policy style of MAJOR.MAJOR.MINOR.PATCH +Yesod packages roughly follow the Haskell Package Versioning Policy style of A.B.C.[D] (MAJOR.MAJOR.MINOR.[PATCH]) -* MAJOR - Used for massive changes in the library -* MAJOR - Used for smaller breaking changes, like removing, renaming, or changing behavior of existing public API. -* MINOR - Used for new public APIs -* PATCH - Used for bug fixes +* A - Used for massive changes in the library. (Example: 1.2.3.4 becomes 2.0.0) +* B - Used for smaller breaking changes, like removing, renaming, or changing behavior of existing public API. (Example: 1.2.3.4 becomes 1.3.0) +* C - Used for new public APIs (Example: 1.2.3.4 becomes 1.2.4) +* D - Used for bug fixes (Example: 1.2.3.4 becomes 1.2.3.5). + * D is optional in the version number, so 2.0.0 is a valid version. Documentation changes don't require a new version. @@ -83,7 +84,7 @@ If you feel there is ambiguity to a change (e.g. fixing a bug in a function, whe Unlike in the Package Versioning Policy, deprecations are not counted as MAJOR changes. -In some cases, dropping compatibility with a major version of a dependency (e.g. changing from transformers >= 0.3 to transformers >= 0.4), is considered a MAJOR breaking change. +In some cases, dropping compatibility with a major version of a dependency (e.g. changing from transformers >= 0.3 to transformers >= 0.4), is considered a breaking change. ### Changelog