|
| 1 | +# Contributing to MapFish Print |
| 2 | + |
| 3 | +Thanks for your interest in contributing to MapFish Print. Please follow Github code of conduct. |
| 4 | + |
| 5 | +## Submitting Issues - Bug Reports |
| 6 | + |
| 7 | +Please use the [GitHub issue tracker](https://github.com/mapfish/mapfish-print/issues). Before creating a new issue, do a quick search to see if the problem has been reported already. Do not hesitate to add a comment if you encountered this issue too. |
| 8 | + |
| 9 | +## Contributing Code |
| 10 | + |
| 11 | +Install then activate pre-commit hooks in your repository: |
| 12 | +(The 'pre-commit install' must be run once per repository) |
| 13 | + |
| 14 | +```bash |
| 15 | +sudo apt install pre-commit |
| 16 | +pre-commit install --allow-missing-config |
| 17 | +``` |
| 18 | + |
| 19 | +Code contributions are made through [pull requests](https://help.github.com/articles/using-pull-requests). Make sure that your pull request follows our pull request guidelines below before submitting it. |
| 20 | + |
| 21 | +## Contributor License Agreement |
| 22 | + |
| 23 | +Your contribution will be under our [license](https://github.com/mapfish/mapfish-print?tab=BSD-2-Clause-1-ov-file) as per [GitHub's terms of service](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license). |
| 24 | + |
| 25 | +## Pull request guidelines |
| 26 | + |
| 27 | +Before working on a pull request, create an issue explaining what you want to contribute. This ensures that your pull request won't go unnoticed, and that you are not contributing something that is not suitable for the project. Once a core developer has set the `pull request accepted` label on the issue, you can submit a pull request. The pull request description should reference the original issue. |
| 28 | + |
| 29 | +Your pull request must: |
| 30 | + |
| 31 | +- Contain a description |
| 32 | + |
| 33 | +- Pass the integration tests run automatically by the Continuous Integration system. |
| 34 | + |
| 35 | +- Address a single issue or add a single item of functionality. |
| 36 | + |
| 37 | +- Contain a clean history of small, incremental, logically separate commits, without merge commits. |
| 38 | + |
| 39 | +- Use clear commit messages. |
| 40 | + |
| 41 | +### Address a single issue or add a single item of functionality |
| 42 | + |
| 43 | +Please submit separate pull requests for separate issues. This allows each to |
| 44 | +be reviewed on its own merits. Some might even be backported, some can not. |
| 45 | + |
| 46 | +### Contain a clean history of small, incremental, logically separate commits, with no merge commits |
| 47 | + |
| 48 | +The commit history explains to the reviewer the series of modifications to the |
| 49 | +code that you have made and breaks the overall contribution into a series of |
| 50 | +easily-understandable chunks. Any individual commit should not add more than |
| 51 | +one new class or one new function. Do not submit commits that change thousands |
| 52 | +of lines or that contain more than one distinct logical change. Trivial |
| 53 | +commits, e.g. to fix lint errors, should be merged into the commit that |
| 54 | +introduced the error. See the [Atomic Commit Convention on Wikipedia](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_Commit_Convention) for more detail. |
| 55 | + |
| 56 | +`git apply --patch` and `git rebase` can help you create a clean commit |
| 57 | +history. |
| 58 | +[Reviewboard.org](https://www.reviewboard.org/docs/codebase/dev/git/clean-commits/) |
| 59 | +and [Pro GIT](https://git-scm.com/book/en/Git-Tools-Rewriting-History) have |
| 60 | +explain how to use them. |
| 61 | + |
| 62 | +### Use clear commit messages |
| 63 | + |
| 64 | +Commit messages should be short, begin with a verb in the imperative, and |
| 65 | +contain no trailing punctuation. We follow |
| 66 | +https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html |
| 67 | +for the formatting of commit messages. |
| 68 | + |
| 69 | +Git commit message should look like: |
| 70 | + |
| 71 | + Header line: explaining the commit in one line |
| 72 | + |
| 73 | + Body of commit message is a few lines of text, explaining things |
| 74 | + in more detail, possibly giving some background about the issue |
| 75 | + being fixed, etc etc. |
| 76 | + |
| 77 | + The body of the commit message can be several paragraphs, and |
| 78 | + please do proper word-wrap and keep columns shorter than about |
| 79 | + 74 characters or so. That way "git log" will show things |
| 80 | + nicely even when it's indented. |
| 81 | + |
| 82 | + Further paragraphs come after blank lines. |
| 83 | + |
| 84 | +Please keep the header line short, no more than 50 characters. |
| 85 | + |
| 86 | +### Be possible to merge automatically |
| 87 | + |
| 88 | +Occasionally other changes to `master` might mean that your pull request cannot |
| 89 | +be merged automatically. In this case you may need to rebase your branch on a |
| 90 | +more recent `master`, resolve any conflicts, and `git push --force` to update |
| 91 | +your branch so that it can be merged automatically. |
0 commit comments