% 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.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.
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 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.

Before submitting your patches, please ensure that they fit the coding
style which is used within the project. To assist with this you can run the
checkpatch.pl script (in scripts) which is able to pinpoint various style
violations on both patches and source code. However, please bear in mind that
checkpatch.pl is not perfect and it may sometimes give bad advice. To quote Ted
Ts'o on LKML: You need to know when the right thing to do is to say, "Go home,
checkpatch, you're drunk."

To use this script, simply invoke it from the command line. If you want to
check a whole file, use the following invocation:

	./scripts/checkpatch.pl -f {yourfile}

To check a patch generated by the command lines above, use the following
invocation:

	./scripts/checkpatch.pl {yourfile}

Correct any error and warning that are reported by the tool. If you think
the tool reported a false positive, please report a bug on the [opkg-devel
mailing list][1].

The additional use of option --ignore CODE_INDENT is encouraged for a
while if you experience some issue related to code indentation. This is
very likely to change in the future as the code base will be streamlined
to use fixed indentation rules.

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][1].

[1]: mailto: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.
