3Thanks for your interest in contributing to Wai! This file has some tips for developing Wai and getting a pull request accepted.
7Wai 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.
9* `stack build mime-types`
10* `stack test auto-update`
13If you'd like to test your changes in a full-fledged Wai app, you can use Stack to build against it, e.g.:
17- '/path/to/this/repo/wai'
24Avoid 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.
28Keep 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.
32Avoid adding unnecessary dependencies. If a dependency provides only a minor convenience for your implementation, it's probably better to skip it.
34If you do add a new dependency, try to support a wide range of versions of it.
36### Backwards Compatibility
38Backwards 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.
40Keep backwards compatibility with old versions of dependencies when possible.
46As much as possible, keep separate changes in separate PRs.
50Tests are recommended, but not required.
54All public APIs must be documented. Documenting private functions is optional, but may be nice depending on their complexity. Example documentation:
57-- | Generate an action which will either read from an automatically
58-- updated value, or run the update action in the current thread.
62-- > getTime <- mkAutoUpdate defaultUpdateSettings
65mkAutoUpdate :: UpdateSettings a -> IO (IO a)
68Examples are recommended, but not required, in documentation. Marking new APIs with `@since <version number>` is required.
72Wai packages roughly follow the Haskell Package Versioning Policy style of A.B.C.[D] (MAJOR.MAJOR.MINOR.[PATCH])
74* A - Used for massive changes in the library. (Example: 1.2.3.4 becomes 2.0.0)
75* 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)
76* C - Used for new public APIs (Example: 1.2.3.4 becomes 1.2.4)
77* D - Used for bug fixes (Example: 1.2.3.4 becomes 1.2.3.5).
78 * D is optional in the version number, so 2.0.0 is a valid version.
80Documentation changes don't require a new version.
82If 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.
84Unlike in the Package Versioning Policy, deprecations are not counted as MAJOR changes.
86In 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.
90After 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.
94Releases 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.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list