Contributing

From RTEMSWiki
Jump to: navigation, search

Contents

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.

If you'd like to contribute in general but aren't sure how you might best do that, see How can I help?

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

See Creating a Patch for details on how to use Git to create patches.

If you do not have the Git repository available then you can 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.

We prefer patches posted as plain text. If the patch is too big posting it gzipped is acceptable but it would be better as a branch that can be pulled/reviewed. Submit your patch to the rtems-devel mailing list and if the patch fixes a bug, file a PR on the Bugzilla.

Submitting

When you have all these pieces email 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.

How can I help?

Firstly, thanks for your interest in contributing! There's plenty you can do to help - and you don't need to be an expert coder, either.

Don't be afraid to announce your interest on the rtems-users mailing list or to ask questions to help you along!

Here're some ideas for work that'd be really useful to RTEMS users. It's non-exhaustive, and largely cobbled together from what's been suggested over time (in fact, one way you might contribute is to update this list with ideas that (for example) have been raised on the mailing lists).

See also the Open Projects page.

Non-coding

  • Documentation - there can (almost) never be too much documentation! Coding types are often accused of neglecting it, but it can be the most important part of a piece of work, particularly for assisting new users, either of RTEMS generally or of a particular feature
    • Read documentation and Wiki articles and try to ensure they're
      • Still relevant and up-to-date
      • Clear, concise and phrased as well as possible
    • Translate documentation
    • Migrate documentation, "where appropriate", from a Wiki article to more formal documents, such as the RTEMS Getting Started guide
    • Update the RTEMS Wiki, which can be a relatively accessible way to have a significant impact on the RTEMS community, particularly assisting new users. First, Request a Wiki account, then, for instance:
      • Add "How To" articles on:
        • Application build systems (might be easier with some coding knowledge) - Make and WAF templates, examples and walkthroughs, for instance, can really help new users find their feet and develop the foundation for the application afresh
      • Correct spelling errors, broken links and so on
      • Unify BSP articles - which at the moment differ substantially from article to article - for example, to list RTEMS features available / not available
      • Peruse the rtems-users mailing list archives for areas in need of clarification
    • The RTEMS Getting Started guide
      • Doesn't mention the (very helpful) RTEMS Source Builder
      • Is generally a bit thin in the post-RTEMS-setup stages, perhaps where it matters most!
      • Doesn't explain that RTEMS is a library that an application is linked against to create a single binary - this can be confusing for users of other RTOSs that operate differently
  • Problem Reports
    • Problem Reports, or PRs are submitted by users to raise attention to a deficiency. Sometimes they're out-of-date and the problem has since been fixed - it can be very helpful to confirm this, perhaps by attempting to reproduce it. Sometimes PRs may have been mis-filed (for example, an RTEMS Source Builder-related problem might be filed under RTEMS, hindering the appropriate people from being alerted)
  • Web site - suggest and/or prototype improvements to the RTEMS Web site

Coding

Personal tools
Namespaces

Variants
Actions
Navigation
Gedare's Special Help
Toolbox