Version 5 (modified by Sh, on Apr 28, 2009 at 4:29:44 PM) (diff)

Added hint to Doxygen recommendations


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

Testing Patches

All patches must be as thoroughly tested as possible. 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.

Much of RTEMS's code is used only by some targets, or used in quite different ways by different targets. When choosing targets to test a patch with, make sure that your selections exercise all aspects of the code you are changing in various RTEMS configurations. For example, a BSP should build with and without networking enabled. 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 the test framework permits, you should automate these tests and add them to RTEMS's test suite. You must also perform regression tests to ensure that your patch does not break anything else.

With documentation changes, you must perform a make and correct any errors. You should investigate complaints about overfull or underfull hboxes from make, as these can be the only indication of serious markup problems, but do not feel obliged to eliminate them all.

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"
    <html xmlns="" 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.

Submitting Patches

Every patch must have several pieces of information before we can properly evaluate it:

  • A description of the problem/bug and how your patch addresses it.
    • For new features a description of the feature and your implementation. For bugs a description of what was wrong with the existing code, and a reference to any previous bug report (in the RTEMS Bugzilla database or one of the RTEMS Mailing Lists) and any existing testcases for the problem in the RTEMS testsuite.
  • Testcases
    • If you cannot follow the recommendations of the RTEMS coding conventions, you should include a justification for why adequate testcases cannot be added. 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.
  • ChangeLog?
    • A ChangeLog? entry as plaintext; see the various ChangeLog? files for format and content and GNU Coding Standards for further information. The ChangeLog? entries should be plaintext rather than part of the patch since the top of the ChangeLog? changes rapidly and a patch to the ChangeLog? would probably no longer apply by the time your patch is reviewed. If your change fixes a PR, put text in the ChangeLog? entry mentioning the PR. In order to be recognized by scripts, the text must fit a particular form. It must start with "PR", and then must include the category and PR number. For instance, Fixes PR bsps/369 is valid. Multiple PRs can be mentioned in a single message with each on a separate line.
  • Compiling and testing
    • State the host and target combinations you used to do the testing described above, and the results of your testing.
  • The patch itself
    • If you are accessing the CVS repository at, 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.