wiki:Developer/Contributing

Version 17 (modified by Gedare, on Mar 4, 2012 at 10:42:09 PM) (diff)

/* Patches */

Contributing

We strongly encourage contributions of code, bug fixes, optimizations, new features, documentation updates, and any other useful changes.

There are certain legal requirements and Coding Conventions 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

See Creating a Patch? with Git.

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.