Add Github issue and PR templates, plus contributing guidelines

* Closes #1450
This commit is contained in:
Maximilian Tagher 2017-11-02 20:16:33 -07:00
parent 299d0569af
commit 42b94f5066
3 changed files with 101 additions and 0 deletions

29
.github/ISSUE_TEMPLATE.md vendored Normal file
View File

@ -0,0 +1,29 @@
<!---
### Bug Reports
Reporting a bug? If relevant, we recommend including:
* Your OS name and version
* The versions of tools you're using (e.g. `stack`, `yesod` `ghc`).
* The versions of dependencies you're using
For your convenience, we recommend pasting this script into bash and uploading the output [as a gist](https://gist.github.com/).
```
command -v sw_vers && sw_vers # OS X only
command -v uname && uname -a # Kernel version
command -v stack && stack --version
command -v stack && stack ghc -- --version
command -v stack && stack list-dependencies
command -v yesod && yesod version
```
* Also, is there anything custom or unusual about your setup? i.e. new or prerelease versions of GHC, stack, etc.
* Finally, if possible, please reproduce the error in a small script, or if necessary create a new Github repo with the smallest possible reproducing case. [Stack's scripting support](https://docs.haskellstack.org/en/stable/GUIDE/#script-interpreter) might be useful for creating your reproduction example.
### 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.
-->

14
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@ -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)
<!---Thanks so much for contributing! :)
_If these checkboxes don't apply to your PR, you can delete them_-->

58
CONTRIBUTING.md Normal file
View File

@ -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 <command> <subproject>`, 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 @<form>@ containing the token.
-> RequestBuilder site ()
```
Examples are appreciated, but not required, in documentation. Marking new APIs with `@since <version number>` 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