wiki:Developer/Contributing

Version 13 (modified by Gedare, on Mar 4, 2012 at 4:40:33 AM) (diff)

/* Patches */

Contributing

RTEMS is an open project with a large and varied group of users. There are always new CPU architectures to port RTEMS to or boards which do not have BSPs. There is also a list of Open Projects so when someone has a brainstorm, it gets captured.

We strongly encourage contributions of code, bug fixes, new optimizations, new features, documentation updates, web page improvements, etc. for RTEMS.

There are certain legal requirements and Coding Conventions issues which all contributions must meet. For in-source documentation please have a look at the Doxygen recommendations.

Legal Requirements

Code published under a pure GPL is not compatible with the RTEMS license and therefore should not be contributed to the RTEMS source tree. The code sections available in RTEMS come with various licenses, but all of the licenses should be compatible with the RTEMS Primary License, which is derived from (but not identical to) the GPL Version 2. Please see http://www.rtems.com/license/LICENSE for the details.

When you submit new code or a substantial modification of existing code please include a copyright notice on top of the source code and the applicable license. If you are not sure which license terms to use for new code, then the RTEMS Primary License is recommended.

Submitting Changes

Every change made to RTEMS must have several pieces of information before we can properly evaluate it:

Description

For new features include a description of the feature and your design/implementation. For bugs a reference to a bug report? should be included.

If you cannot follow the recommendations of the RTEMS coding conventions, you should include a justification for why. If you are submitting a port of code from another free software project, then that code should NOT be reformatted for RTEMS. It needs to stay as close to the original source as possible to ease future update efforts.

Testing

We encourage you to test changes with as many host and target combinations as is practical. In addition to using real hardware, you can use simulators? to increase your test coverage. When choosing targets to test a patch with try to exercise all aspects of the code you are changing in various RTEMS configurations. Also remember that RTEMS supports targets with 16, 32, and 64 bit integers. This means that much of the RTEMS source tree must build without warnings on ALL of those targets.

Sometimes a change is mechanical in nature and just verifying it compiles all impacted configurations is sufficient.

You will of course have tested that your change does what you expected it to do: fix a bug, improve an optimization, add a new feature. If possible you should automate your test cases and add them to RTEMS's test suite. You should also perform regression tests to ensure that your patch does not break anything else.

With documentation changes, you must make the doc manuals and correct any errors.

In all cases you must test exactly the change that you intend to submit; it's not good enough to test an earlier variant. The tree where you perform this test should not have any other changes applied to it, because otherwise you cannot be sure that your patch will work correctly on its own. Include all your new test cases in your testsuite run.

Patches

A patch is a text file containing the difference between an old and new version of code. If you are using the Git repository see the Git patch instructions? for how to generate patches to submit. If you do not have the Git repository available then you should use the diff program to create a patch by comparing an unmodified RTEMS against the version containing your changes with diff -up rtems rtems-new and redirect the output to a file.

Patches against current development (git head) are preferred to patches against releases unless your patch is intended as a bug fix candidate for a release branch.

Send one patch for each logical change made. Each patch you submit should be impossible to subdivide into more patches because of dependencies between the changed parts.

Patches that fix code formatting to conform to our standards are best not mixed with substantive changes and vice versa, because the code reformatting hides the functional changes.

We prefer patches posted as plain text. Also acceptable are MIME parts of type text/x-patch or text/plain, disposition inline, encoded as 7bit or 8bit. If the patch is too big or too mechanical, posting it gzipped or bzip2ed and uuencoded or encoded as a base64 MIME part is acceptable. Other than that, it is strongly discouraged to post patches as MIME parts of type application/whatever, disposition attachment and/or encoded as base64 or quoted-printable. Avoid MIME large-message splitting (message/partial) at all costs.

Submitting

When you have all these pieces send them to the developers mailing list or post a bug report?. All patches and related discussion should be sent to the rtems-devel mailing list. For further information on the RTEMS Git repository, see Git.

If you do not receive a response to a patch within a month or so, send a follow-up email. Patches occasionally fall through the cracks. Please be sure to include the URL of the entry in the mailing list archive of the original submission.

Everything listed here still applies if you can check in the patch without further approval under the RTEMS write access policies.