Changes between Version 7 and Version 8 of Developer/Contributing


Ignore:
Timestamp:
Mar 4, 2012, 4:22:38 AM (8 years ago)
Author:
Gedare
Comment:

Rearrange contents

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Contributing

    v7 v8  
    1919
    2020When 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.
    21 = Testing Patches =
     21= Submitting Changes =
    2222
    2323
    24 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 [wiki:Emulator  simulators] to increase your test coverage.
     24Every change made to RTEMS must have several pieces of information before we can properly evaluate it:
     25= Description =
    2526
    26 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. 
     27 *  A description of the change.
     28  *  For new features include a description of the feature and your implementation. For bugs a reference to a [wiki:Bugzilla bug report] should be included.
     29  *  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.
     30= ChangeLog =
     31
     32  *  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.
     33= Testing =
     34
     35
     36We encourage you to test changes with as many host and target combinations as is practical. In addition to using real hardware, you can use [wiki:Emulator  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. 
    2737
    2838Sometimes a change is mechanical in nature and just verifying it compiles all impacted configurations is sufficient.
    2939
    30 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.
     40You 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.
    3141
    32 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.
     42With documentation changes, you must make the doc manuals and correct any errors.
    3343
    3444Changes 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.
     
    4353
    4454In 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.
    45 = Submitting Patches =
     55= Patches =
    4656
    47 
    48 Every patch must have several pieces of information before we can properly evaluate it:
    49 
    50  *  A description of the problem/bug and how your patch addresses it.
    51   *  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.
    52 
    53  *  Testcases
    54   *  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.
    55 
    56  *  ChangeLog
    57   *  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.
    58 
    59  *  Compiling and testing
    60   *  State the host and target combinations you used to do the testing described above, and the results of your testing.
    61 
    62  *  The patch itself
    6357  *  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.
    6458