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