1# libCEED: How to Contribute 2 3Contributions to libCEED are encouraged. 4<!--- 5Please use a pull request to the appropriate branch ('maint' for 6backward-compatible bug fixes for the last stable release, 'master' for 7new features and everything else). 8--> 9Please make your commits well-organized and 10[atomic](https://en.wikipedia.org/wiki/Atomic_commit#Atomic_commit_convention), 11using `git rebase --interactive` as needed. Check that tests 12(including "examples") pass using `make prove-all`. If adding a new 13feature, please add or extend a test so that your new feature is 14tested. 15 16In typical development, every commit should compile, be covered by the 17test suite, and pass all tests. This improves the efficiency of 18reviewing and facilitates use of 19[`git bisect`](https://git-scm.com/docs/git-bisect). 20 21Open an issue or RFC (request for comments) pull request to discuss 22any significant changes before investing time. It is useful to create 23a WIP (work in progress) pull request for any long-running development 24so that others can be aware of your work and help to avoid creating 25merge conflicts. 26 27Write commit messages for a reviewer of your pull request and for a 28future developer (maybe you) that bisects and finds that a bug was 29introduced in your commit. The assumptions that are clear in your 30mind while committing are likely not in the mind of whomever (possibly 31you) needs to understand it in the future. 32 33Give credit where credit is due using tags such as `Reported-by: 34Helpful User <helpful@example.com>` or 35[`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). 36Please use a real name and email for your author information (`git 37config user.name` and `user.email`). If your author information or 38email becomes inconsistent (look at `git shortlog -se`), please edit 39`.mailmap` to obtain your preferred name and email address. 40 41Please avoid "merging from upstream" (like merging 'master' into your 42feature branch) unless there is a specific reason to do so, in which 43case you should explain why in the merge commit. 44[Rationale](https://lwn.net/Articles/328436/) from 45[Junio](https://gitster.livejournal.com/42247.html) and 46[Linus](http://yarchive.net/comp/linux/git_merges_from_upstream.html). 47 48You can use `make style` to help conform to coding conventions of the 49project, but try to avoid mixing whitespace or formatting changes with 50content changes (see atomicity above). 51 52By submitting a pull request, you are affirming the following. 53 54## [Developer's Certificate of Origin 1.1](https://developercertificate.org/) 55 56By making a contribution to this project, I certify that: 57 58(a) The contribution was created in whole or in part by me and I 59 have the right to submit it under the open source license 60 indicated in the file; or 61 62(b) The contribution is based upon previous work that, to the best 63 of my knowledge, is covered under an appropriate open source 64 license and I have the right under that license to submit that 65 work with modifications, whether created in whole or in part 66 by me, under the same open source license (unless I am 67 permitted to submit under a different license), as indicated 68 in the file; or 69 70(c) The contribution was provided directly to me by some other 71 person who certified (a), (b) or (c) and I have not modified 72 it. 73 74(d) I understand and agree that this project and the contribution 75 are public and that a record of the contribution (including all 76 personal information I submit with it, including my sign-off) is 77 maintained indefinitely and may be redistributed consistent with 78 this project or the open source license(s) involved. 79 80## Authorship 81 82libCEED contains components authored by many individuals. It is 83important that contributors receive appropriate recognition through 84informal and academically-recognized credit systems such as 85publications. Status as a named author on the users manual and 86libCEED software publications will be granted for those who 87 881. make significant contributions to libCEED (in implementation, 89 documentation, conceptualization, review, etc.) and 902. maintain and support those contributions. 91 92Maintainers will do their best to notice when contributions reach this 93level and add your name to `AUTHORS`, but please email or create an 94issue if you believe your contributions have met these criteria and 95haven't yet been acknowledged. 96 97Authors of publications about libCEED as a whole, including 98DOI-bearing archives, shall offer co-authorship to all individuals 99listed in the `AUTHORS` file. Authors of publications claiming 100specific libCEED contributions shall evaluate those listed in 101`AUTHORS` and offer co-authorship to those who made significant 102intellectual contributions to the work. 103 104Note that there is no co-authorship expectation for those publishing 105about use of libCEED (versus creation of new features in libCEED), but 106see [`CITING.md`](CITING.md) and use your judgment regarding 107significance of support/advice you may have received in developing 108your use case and interpreting results. 109