wiki:Developer/Contributing

Version 9 (modified by Gedare, on Mar 4, 2012 at 4:22:56 AM) (diff)

Prune ChangeLog?

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

The code sections available in RTEMS come with various different licenses, but all of the licenses should be compatible with the RTEMS Primary License, which is derived (but not identical) from the GPL Version 2. Please see http://www.rtems.com/license/LICENSE for the details.

Due to the RTEMS-specific modification of the GPL, code published under a pure GPL is not compatible with the RTEMS license and therefore should not be contributed to the RTEMS source tree.

When you submit new code or a substantial modification of existing code, please don't forget your copyright notice on top of the source code, also specifying the type of license applicable. 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

  • A description of the change.
    • For new features include a description of the feature and your 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.

Changes to the web site must validate as XHTML 1.0 Transitional. The web pages as checked into CVS do not include DOCTYPE declarations; they are automatically added when the web server checks out its copy. To validate your changes, temporarily insert this header in place of the <html> tag, then use the "upload file" mode of the validator.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE html 
              PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
              "DTD/xhtml1-transitional.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

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

  • If you are accessing the CVS repository at www.rtems.com, use "cvs update; cvs diff -c3p"; else, use "diff -c3p OLD NEW" or "diff -up OLD NEW". If your version of diff does not support these options, then get the latest version of GNU diff. Patches against current development (mainline CVS) are preferred to patches against releases, unless your patch is intended as a candidate for the release branch.

Don't mix together changes made for different reasons. Send them individually. Ideally, each change you send should be impossible to subdivide into parts that we might want to consider separately, because each of its parts gets its motivation from the other parts. In particular, changes to code formatting to conform to coding standards are best not mixed with substantive changes, because that makes it difficult to see what the real changes are. (In the case of a very large reorganization of code, it may make sense to separate changes even further to make it clearer what has changed; for example, by first sending structural changes that make subsequent changes easier but do not change RTEMS's behavior, then new code, then the changes that actually make use of the new code and change RTEMS's behavior.)

We prefer patches posted as plain text or as 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, as long as the ChangeLog? is still posted as plain text. 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.

When you have all these pieces, bundle them up in a mail message and send it to rtems-users@…". All patches and related discussion should be sent to the rtems-users mailing list. For further information on the RTEMS CVS repository, see the Anonymous read-only CVS access and Read-write CVS access pages.

If you do not receive a response to a patch that you have submitted within a month or so, it may be a good idea to chase it by sending a follow-up email to rtems-users@…" or a member or the RTEMS Steering Committee. Patches can 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, except that ChangeLog? entries may be included as part of the patch since no-one else will need to apply it to the tree later and diffs representing totally new files may be omitted (especially if large) since they can be accessed directly from the repository.