git.iko.soy/obelisk
on master help sign in
obelisk/CONTRIBUTING.md
131 lines 5.1 kB history raw
1# Contribution Guide
3Contributions and issue reports are encouraged and appreciated!
5- [Opening Issues](#opening-issues)
6- [Submitting Changes](#submitting-changes)
7 - [Guidelines for Commit Messages](#guidelines-for-commit-messages)
8 - [Guidelines for Pull Requests](#guidelines-for-pull-requests)
9 - [Code Quality](#code-quality)
10 - [Documentation](#documentation)
11- [Development Environment](#development-environment)
13## Opening Issues
15Before opening an issue, please check whether your issue has already been reported. Assuming it has not:
17* Describe the issue you're encountering or the suggestion you're making
18* Include any relevant steps to reproduce or code samples you can. It's always easier for us to debug if we have something that demonstrates the error.
19* Let us know what version of this project you were using. If you're using a github checkout, provide the git hash.
21## Submitting Changes
23Most pull requests should target the `develop` branch. `master` is the release branch. `develop` is periodically merged into master after a period of testing.
25### Guidelines for Commit Messages
27#### Summary Line
28The summary line of your commit message should summarize the changes being made. Commit messages should be written in the imperative mood and should describe what happens when the commit is applied. If your commit modifies one of the in-tree haskell packages (found in `./lib`), please prefix your commit summary with the name of the package being modified.
30One way to think about it is that your commit message should be able to complete the sentence:
31"When applied, this commit will..."
33##### Note on bumping dependencies
34Commits that update a dependency should include some information about why the dependency was updated in the commit message.
36#### Body
37For breaking changes, new features, refactors, or other major changes, the body of the commit message should describe the motivation behind the change in greater detail and may include references to the issue tracker. The body shouldn't repeat code/comments from the diff.
39### Guidelines for Pull Requests
41Wherever possible, pull requests should add a single feature or fix a single bug. Pull requests should not bundle several unrelated changes.
44### Code Quality
46#### Warnings
48Your pull request should add no new warnings to the project. It should also generally not disable any warnings.
50#### Build and Test
52Make sure the project builds and that the tests pass! This will generally also be checked by CI before merge, but trying it yourself first means you'll catch problems earlier and your contribution can be merged that much sooner!
54You can run the tests like this:
55```bash
56$(nix-build -A selftest --no-out-link)
57```
59To test that your changes build across platforms, you can also try to build release.nix, like this:
60```bash
61nix-build release.nix
62```
64Note, however, that to build release.nix you must accept the android license agreement and your machine must be configured to build both ios and android executables (usually via remote builders).
67### Documentation
69#### In the code
70We're always striving to improve documentation. Please include [haddock](https://haskell-haddock.readthedocs.io/en/latest/index.html) documentation for any added code, and update the documentation for any code you modify.
72#### In the [Changelog](ChangeLog.md)
73Add an entry to the changelog when your PR:
74* Adds a feature
75* Deprecates something
76* Includes a breaking change
77* Makes any other change that will impact users
79#### In the [Readme](README.md)
80The readme is the first place a lot of people look for information about the repository. Update any parts of the readme that are affected by your PR.
83## Development Environment
85There are two ways to get live compiler feedback while developing Obelisk libraries. For libraries that are dependencies of the `skeleton` application, the easiest way to get feedback is to
87```bash
88cd skeleton
89ob run
90```
92This `ob run` session only loads modules that are dependencies of the skeleton and `obelisk-run`. For example, `obelisk-asset` and `obelisk-route` are used by the skeleton.
94For other libraries like `obelisk-command` you can use `ghcid`. To launch `ghcid` for `lib/command` you can run
96```bash
97nix-shell -A obeliskEnvs.obelisk-command --run "cd lib/command && ghcid"
98```
100### Building `ob` for testing
102To re-install `ob` from source globally you can do
104```bash
105nix-env -f /path/to/obelisk -iA command
106```
108You can also open a shell with the local version of `ob` available on your `$PATH`:
110```bash
111nix run -f /path/to/obelisk command
112```
114### Hacking on Obelisk from within an Obelisk project
116`ob` will defer to the version found in your project's `.obelisk/impl` directory. To work on that version specifically:
118```bash
119ob thunk unpack ./.obelisk/impl
120cd ./.obelisk/impl
121# apply your changes
122```
124If you want to commit your changes, first push them to your fork of obelisk and then
126```bash
127cd /your/project/root
128ob thunk pack .obelisk/impl
129git add .obelisk/impl
130git commit -m "Bump obelisk"
131```