15d6bafb2Sjeremylt# libCEED: How to Contribute 274e0540eSJed Brown 399276e83SJed BrownContributions to libCEED are encouraged. 4ee7e4e48Sjeremylt<!--- 574e0540eSJed BrownPlease use a pull request to the appropriate branch ('maint' for 674e0540eSJed Brownbackward-compatible bug fixes for the last stable release, 'master' for 774e0540eSJed Brownnew features and everything else). 8ee7e4e48Sjeremylt--> 999276e83SJed BrownPlease make your commits well-organized and 1099276e83SJed Brown[atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention), 1199276e83SJed Brownusing `git rebase --interactive` as needed. Check that tests 1299276e83SJed Brown(including "examples") pass using `make prove-all`. If adding a new 1399276e83SJed Brownfeature, please add or extend a test so that your new feature is 1499276e83SJed Browntested. 1599276e83SJed Brown 1699276e83SJed BrownIn typical development, every commit should compile, be covered by the 1799276e83SJed Browntest suite, and pass all tests. This improves the efficiency of 1899276e83SJed Brownreviewing and facilitates use of 1999276e83SJed Brown[`git bisect`](https://git-scm.com/docs/git-bisect). 2099276e83SJed Brown 2199276e83SJed BrownOpen an issue or RFC (request for comments) pull request to discuss 2299276e83SJed Brownany significant changes before investing time. It is useful to create 2399276e83SJed Browna WIP (work in progress) pull request for any long-running development 2499276e83SJed Brownso that others can be aware of your work and help to avoid creating 2599276e83SJed Brownmerge conflicts. 2674e0540eSJed Brown 2774e0540eSJed BrownWrite commit messages for a reviewer of your pull request and for a 2874e0540eSJed Brownfuture developer (maybe you) that bisects and finds that a bug was 2999276e83SJed Brownintroduced in your commit. The assumptions that are clear in your 3099276e83SJed Brownmind while committing are likely not in the mind of whomever (possibly 3199276e83SJed Brownyou) needs to understand it in the future. 3299276e83SJed Brown 3399276e83SJed BrownGive credit where credit is due using tags such as `Reported-by: 34*b4d76956SJed BrownHelpful User <helpful@example.com>` or 35*b4d76956SJed Brown[`Co-authored-by: Snippet Mentor <code.by@comment.com>`](https://help.github.com/en/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors#creating-co-authored-commits-on-the-command-line). 36*b4d76956SJed BrownPlease use a real name and email for your author information (`git 37*b4d76956SJed Brownconfig user.name` and `user.email`). If your author information or 38*b4d76956SJed Brownemail becomes inconsistent (look at `git shortlog -se`), please edit 39*b4d76956SJed Brown`.mailmap` to obtain your preferred name and email address. 4074e0540eSJed Brown 4174e0540eSJed BrownPlease avoid "merging from upstream" (like merging 'master' into your 4274e0540eSJed Brownfeature branch) unless there is a specific reason to do so, in which 4374e0540eSJed Browncase you should explain why in the merge commit. 4474e0540eSJed Brown[Rationale](https://lwn.net/Articles/328436/) from 4574e0540eSJed Brown[Junio](https://gitster.livejournal.com/42247.html) and 4674e0540eSJed Brown[Linus](http://yarchive.net/comp/linux/git_merges_from_upstream.html). 4774e0540eSJed Brown 4899276e83SJed BrownYou can use `make style` to help conform to coding conventions of the 4999276e83SJed Brownproject, but try to avoid mixing whitespace or formatting changes with 5099276e83SJed Browncontent changes (see atomicity above). 5199276e83SJed Brown 5274e0540eSJed BrownBy submitting a pull request, you are affirming the following. 5374e0540eSJed Brown 54288c0443SJeremy L Thompson## [Developer's Certificate of Origin 1.1](https://developercertificate.org/) 5574e0540eSJed Brown 5674e0540eSJed BrownBy making a contribution to this project, I certify that: 5774e0540eSJed Brown 5874e0540eSJed Brown(a) The contribution was created in whole or in part by me and I 5974e0540eSJed Brown have the right to submit it under the open source license 6074e0540eSJed Brown indicated in the file; or 6174e0540eSJed Brown 6274e0540eSJed Brown(b) The contribution is based upon previous work that, to the best 6374e0540eSJed Brown of my knowledge, is covered under an appropriate open source 6474e0540eSJed Brown license and I have the right under that license to submit that 6574e0540eSJed Brown work with modifications, whether created in whole or in part 6674e0540eSJed Brown by me, under the same open source license (unless I am 6774e0540eSJed Brown permitted to submit under a different license), as indicated 6874e0540eSJed Brown in the file; or 6974e0540eSJed Brown 7074e0540eSJed Brown(c) The contribution was provided directly to me by some other 7174e0540eSJed Brown person who certified (a), (b) or (c) and I have not modified 7274e0540eSJed Brown it. 7374e0540eSJed Brown 7474e0540eSJed Brown(d) I understand and agree that this project and the contribution 7574e0540eSJed Brown are public and that a record of the contribution (including all 7674e0540eSJed Brown personal information I submit with it, including my sign-off) is 7774e0540eSJed Brown maintained indefinitely and may be redistributed consistent with 7874e0540eSJed Brown this project or the open source license(s) involved. 7974e0540eSJed Brown 80*b4d76956SJed Brown## Authorship 8174e0540eSJed Brown 82*b4d76956SJed BrownlibCEED contains components authored by many individuals. It is 83*b4d76956SJed Brownimportant that contributors receive appropriate recognition through 84*b4d76956SJed Browninformal and academically-recognized credit systems such as 85*b4d76956SJed Brownpublications. Status as a named author on the users manual and 86*b4d76956SJed BrownlibCEED software publications will be granted for those who 87*b4d76956SJed Brown 88*b4d76956SJed Brown1. make significant contributions to libCEED (in implementation, 89*b4d76956SJed Brown documentation, conceptualization, review, etc.) and 90*b4d76956SJed Brown2. maintain and support those contributions. 91*b4d76956SJed Brown 92*b4d76956SJed BrownMaintainers will do their best to notice when contributions reach this 93*b4d76956SJed Brownlevel and add your name to `AUTHORS`, but please email or create an 94*b4d76956SJed Brownissue if you believe your contributions have met these criteria and 95*b4d76956SJed Brownhaven't yet been acknowledged. 96*b4d76956SJed Brown 97*b4d76956SJed BrownAuthors of publications about libCEED as a whole, including 98*b4d76956SJed BrownDOI-bearing archives, shall offer co-authorship to all individuals 99*b4d76956SJed Brownlisted in the `AUTHORS` file. Authors of publications claiming 100*b4d76956SJed Brownspecific libCEED contributions shall evaluate those listed in 101*b4d76956SJed Brown`AUTHORS` and offer co-authorship to those who made significant 102*b4d76956SJed Brownintellectual contributions to the work. 103*b4d76956SJed Brown 104*b4d76956SJed BrownNote that there is no co-authorship expectation for those publishing 105*b4d76956SJed Brownabout use of libCEED (versus creation of new features in libCEED), but 106*b4d76956SJed Brownsee [`CITING.md`](CITING.md) and use your judgment regarding 107*b4d76956SJed Brownsignificance of support/advice you may have received in developing 108*b4d76956SJed Brownyour use case and interpreting results. 109