Commit Policy

From Openembedded

Changes vary in their scope for causing problems. A change in some obscure recipe which few people use is much less likely to impact people than a change to a key file like a .bbclass.

As guidelines:

 * Changes to class files need review
 * Changes to more global .conf files need review (e.g. bitbake.conf)
 * Changes to core toolchain components need review (gcc, binutils, 
   libtool, pkgconfig, automake, autoconf etc.)
 * Machine configs are less sensitive but machine maintainers should be 
   consulted where present and known
 * Distro config changes should be reviewed by the distro maintainers 
   where known
 * Recipe changes are less sensitive but maintainers should be consulted 
   where known

"Review" is defined as posting it on the mailing lists and getting positive agreement from two or more core developers.

Changing the core infrastructure can influence a lot of people and whilst we don't want to discourage people hacking on it, more care is needed in those areas compared to individual recipes.

Other tips for making good commits:

 * Split your changes into their logical subparts. It's easier to 
   track down problems afterwards with a binary search and also people can then
   cherrypick changes into things like stable branches.

 * Have a clear commit message (example):
    - The first line of commit is a summary of the changes.
    - The first line should start with the name of the recipe the change affects.
    - The rest of the message should give more details on the change as appropriate.
    - Mention the affected bug numbers if appropriate.
    - Give credit where credit is due. If you commit someone else's work more or 
      less verbatim, you should use git commit --author $mail-of-author. If pulling
      changes from somewhere like Poky or OpenMoko there is no problem with that
      but mention where the changes came from.
    - Include a Signed-off-by: line indicating the change has valid certificate 
      of origin as per the Linux kernel

 * It's fine to fix a recipe you don't maintain, but its polite to talk to 
   any else actively maintaining that recipe. Try to contact the maintainer 
   or, if no maintainer is listed, send a note to the OE developer mailing list. 

 * Think twice before using an override, usually overrides can be 
   avoided, especially ones like these:

     do_compile() {
         oe_runmake
     } 

     do_compile_myfirstdisto() {
         oe_runmake -D_GNU_SOURCE
     }

   You may think "I don't want to break other distributions", but in 
   99% of the cases your fix will unbreak other distros as well, so using 
   an override will cause more work for other developers, since they have 
   to work out the fix by themselves. You don't want other people to spend 
   weeks trying to solve a problem which solution is masked by a bogus 
   override.

   If an override is really needed, its probably useful to document why its been	
   added and why most people wouldn't want to use it.

 * Sync early, sync often. Nobody likes to reinvent the wheel. Merging 
   is easy with git, so don't hesitate to run sync just before your 
   plane takes off and your wifi gets disconnected.

Above all else, commits are based on a gentleman's agreement. The above rules are not hard fast rules and the changes people are able to commit are also based on that developer's experience.

Anyone found to be committing things inappropriately could have the access to the repository revoked (a decision from the core team is needed for that).

More draconian review and commit policies can be implemented for topic branches such as the stable branch. For consistency, these should be documented in a README file in the branch so people can easily find out about submitting changes (this can point to a webpage if appropriate).