1# libCEED: How to Contribute 2 3Contributions to libCEED are encouraged. 4<!--- 5Please use a pull request to the appropriate branch ('stable' for 6backward-compatible bug fixes for the last stable release, main' 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 41When contributors make a major contribution and support it, their names 42are included in the automatically generated user-manual documentation. 43 44Please avoid "merging from upstream" (like merging 'main' into your 45feature branch) unless there is a specific reason to do so, in which 46case you should explain why in the merge commit. 47[Rationale](https://lwn.net/Articles/328436/) from 48[Junio](https://gitster.livejournal.com/42247.html) and 49[Linus](http://yarchive.net/comp/linux/git_merges_from_upstream.html). 50 51You can use `make style` to help conform to coding conventions of the 52project, but try to avoid mixing whitespace or formatting changes with 53content changes (see atomicity above). 54 55By submitting a pull request, you are affirming the following. 56 57## [Developer's Certificate of Origin 1.1](https://developercertificate.org/) 58 59By making a contribution to this project, I certify that: 60 61(a) The contribution was created in whole or in part by me and I 62 have the right to submit it under the open source license 63 indicated in the file; or 64 65(b) The contribution is based upon previous work that, to the best 66 of my knowledge, is covered under an appropriate open source 67 license and I have the right under that license to submit that 68 work with modifications, whether created in whole or in part 69 by me, under the same open source license (unless I am 70 permitted to submit under a different license), as indicated 71 in the file; or 72 73(c) The contribution was provided directly to me by some other 74 person who certified (a), (b) or (c) and I have not modified 75 it. 76 77(d) I understand and agree that this project and the contribution 78 are public and that a record of the contribution (including all 79 personal information I submit with it, including my sign-off) is 80 maintained indefinitely and may be redistributed consistent with 81 this project or the open source license(s) involved. 82 83## Authorship 84 85libCEED contains components authored by many individuals. It is 86important that contributors receive appropriate recognition through 87informal and academically-recognized credit systems such as 88publications. Status as a named author on the users manual and 89libCEED software publications will be granted for those who 90 911. make significant contributions to libCEED (in implementation, 92 documentation, conceptualization, review, etc.) and 932. maintain and support those contributions. 94 95Maintainers will do their best to notice when contributions reach this 96level and add your name to `AUTHORS`, but please email or create an 97issue if you believe your contributions have met these criteria and 98haven't yet been acknowledged. 99 100Authors of publications about libCEED as a whole, including 101DOI-bearing archives, shall offer co-authorship to all individuals 102listed in the `AUTHORS` file. Authors of publications claiming 103specific libCEED contributions shall evaluate those listed in 104`AUTHORS` and offer co-authorship to those who made significant 105intellectual contributions to the work. 106 107Note that there is no co-authorship expectation for those publishing 108about use of libCEED (versus creation of new features in libCEED), but 109see the [citing section](https://libceed.readthedocs.io/en/latest/gettingstarted/#how-to-cite) 110and use your judgment regarding significance of support/advice you may have 111received in developing your use case and interpreting results. 112