CONTRIBUTING: New guidelines for contributors

Signed-off-by: Paul Barker <paul@paulbarker.me.uk>

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.