eCos Home
RedBoot Home
About eCos
Supported Hardware
Downloading and Installation
Documentation
FAQ
Mailing lists
Problems
Licensing
Anonymous CVS
Contributions and Development Projects
Legal
|
What makes a good eCos patch
Revision 1.0
eCos has relatively relaxed rules about what criteria must be
fulfilled before a patch is accepted. Nevertheless, there are some key
points to follow if you do not wish to be asked by an eCos maintainer
to resubmit your patch. Following these guidelines will also make the
maintainers' job easier and will lead to your patch being applied sooner:
- All patches should be submitted in an appropriate format (see
the section on generating patches).
- Patches should be made against the
development repository in CVS. Patches against the most recent
stable release of eCos will be considered, but if the area involved has
changed greatly since that release, you will be asked to resubmit your patch
against CVS.
- Non-trivial contributed code requires a copyright assignment (see
the section on assigning copyright)
- Patches must have ChangeLog entries, and all new packages must have top
level ChangeLog files. The
GNU Coding
Standards contain a
section on how
to write ChangeLog entries. Contributors should follow this style, although
existing ChangeLogs will also give guidance as to the expectations. Significant
additions or enhancements, such as a new port, may warrant an entry in the
top-level NEWS file.
- Patches should either follow the coding standard for the file patched,
or that from which the file was derived. However, eCos is now intending to
consolidate around the GNU
coding standards for future new files, and we will warmly accept any
patches conforming to those standards.
- All patches which add new features to eCos should include documentation,
preferably in DocBook format to allow direct integration into the eCos
documentation set.
- All patches which modify existing documented behaviour must include a
patch to the documentation.
- Patches must not break established behaviour that existing applications
may rely on.
- Almost needless to say, patches must be tested.
- In particular, in "core" code, just because a patch fixes your problem,
make sure it would not break anything for anyone else. A patch that regresses
existing behaviour e.g. breaking existing drivers for other platforms, will not
be applied however otherwise worthy.
Instead, functionality that changes existing behaviour may only be included
if made configurable by a CDL option (defaulting to the value to preserve
existing behaviour).
- Similarly, changes which will increase ROM/RAM footprint or execution
time in a non-trivial way would probably be better off as a CDL option to
allow it to be disabled, or have the resources limited (e.g. buffer sizes, etc.)
- Including a new test for the functionality the patch covers, or
extending an existing test is highly desirable and will lead to a
patch being included sooner as it is easier to verify.
- New code or functions must be careful to avoid polluting the
namespace. The cyg_ prefix (or hal_ for HAL files)
is conventionally used for all identifiers in the public
namespace. eCos is not perfect in this regard at present, but we do
not wish to make the situation worse.
Even if you do follow these guidelines to the letter, there is no
guarantee that the maintainers will accept the patch. The maintainers
have a duty to the eCos community to ensure eCos stays stable and
maintainable. Anything that performs "open heart surgery" on an
important piece of code, or which takes eCos in a strategic direction the
maintainers do not think eCos should go in may be rejected. Such
patches can always be placed on the contributions page.
|