diff options
Diffstat (limited to 'CONTRIBUTING')
| -rw-r--r-- | CONTRIBUTING | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/CONTRIBUTING b/CONTRIBUTING new file mode 100644 index 0000000..6fc88a4 --- /dev/null +++ b/CONTRIBUTING @@ -0,0 +1,155 @@ +% Contributing to opkg + +## Starting off + +To contribute to opkg, you'll need a basic understanding of how to use git. +You'll also need to make sure you can use `git send-email` - maybe try sending a +few patches to your own email address first to check you've got it set up +correctly. + +If you don't have the latest opkg sources, you'll need to clone the official +repository: + + git clone git://git.yoctoproject.org/opkg.git + +## Contributing bugfixes to a release branch + +Currently, all new feature development takes place on the master branch and we +have one maintained release branch (currently opkg-0.2.x). This simple branching +strategy might need to change once we reach version 1.0 but it should work for +now. + +If you're developing new features or making backwards incompatible changes, base +your work on the master branch. + +If your patch fixes a bug in a released version of opkg, it would be good to +base it off the maintained release branch rather than to the master branch. That +way it can be included in a bugfix release. To do this, checkout the release +branch before developing your fix and ensure the patch email is sent with a +prefix indicating which branch it applies to. The following commands would do +this for the opkg-0.2.x branch: + + git checkout opkg-0.2.x + git config format.subjectprefix "opkg-0.2.x PATCH" + +## Developing patches + +The make and commit your changes (that bit is left as an exercize for the +reader). Developing on a separate branch is a very good idea: + + git checkout -b my-branch + git add ... # As appropriate + git commit -s # As appropriate + +Adding a "Signed-off-by" line (using the -s option to `git commit`) is very +important and signifies acceptance of the Developer's Certificate of Origin (see +appendix). We also accept "Cc", "Acked-by" and "Tested-by" lines as appropriate, +as per the [submission guidelines for the Linux kernel][1]. We're not currently +interested in "Reviewed-by", "Reported-by" or "Suggested-by" lines. + +The subject (first line of the commit message) for each patch should begin with +the submodule, file or function that is modified, followed by a short (<50 +characters if possible) description of the change. That helps +a lot to find anything related to a submodule or file by searching with a +simple 'git log | grep [foo]'. + +Examples of good subjects: + + libopkg: changing searching order for packages + opkg_conf_init: adding new field 'short_desc' + src/opkg-cl.c: fixed return value in function foo + +The remainder of the commit message should explain in detail what was changed +and why. + +Each patch should make a single logical change. If multiple files are changed to +fix one bug or add one feature, that should be a single patch. If one file is +changed to fix multiple bugs, that should be multiple patches. + +[1]: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches + +## Testing + +Assuming you have python (version 3 or later) installed on your system, you can +test your patches by running the 'test-branch.py' script in the 'tests' +directory: + + python3 ./tests/test-branch.py + +By default, this compiles and runs the test suite for each patch between +'master' (which should be the latest upstream code) and 'HEAD' (which will be +your latest commit). If your patches apply to a different branch (eg. +opkg-0.2.x), you need to set the OPKG_MASTER environment variable when you run +the script: + + OPKG_MASTER=opkg-0.2.x python3 ./tests/test-branch.py + +## Submitting patches for review + +Please submit all patches to the opkg mailing list (opkg-devel@googlegroups.com) +and Cc the maintainer (paul@paulbarker.me.uk). Also make sure that you use the +-M option on the command line or the "diff.renames=copy" option in your config. + +That sounds like a lot to remember but if you run the following commands in your +opkg directory it will all be done automatically when you use `git format-patch` +or `git send-email`: + + git config format.to "opkg-devel@googlegroups.com" + git config format.cc "paul@paulbarker.me.uk" + git config diff.renames copy + +To prepare your patches, assuming you took the advice before about developing on +a separate branch: + + git format-patch master + +You can add `--cover-letter` to that command if you want to include a +descriptive email along with your patches. + +Once you've checked the generated patch files, run: + + git send-email + +That should result in your patches being sent to the relevant mailing lists in +the correct format. The patches should then be reviewed and you should receive +feedback by email. If you haven't heard anything within 2 weeks, feel free to +send us a reminder. + +If you need any further help or advice, just ask on the opkg-devel mailing list +(opkg-devel@googlegroups.com). + +## Commit Access + +If you have commit access to the opkg git repository, it is assumed that you +know what you're doing. You can bypass the mailing list and push your changes +directly to the public repository, just make sure that you test things properly +and sign off your patches! + +Appendix: Developer's Certificate of Origin +=========================================== + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. |