XCAT 2 Contribution Guildelines
From xcat
xCAT 2 Contribution Guidelines
To Prepare for Contributing Code to xCAT:
Before Committing Any Code to xCAT's SVN Repository, Please Follow These Guidelines:
- Post to the mailing list about what bug you plan to fix or what new feature you plan to implement. This gives everyone else a chance to know what you are working on, gives the xCAT architects a chance to comment on whether this is consistent with the rest of xCAT, and can help other developers avoid having to do a big merge of their code if they happen to be working on the same files.
- Changes to common xCAT Perl library routines, and the Database Schema must be reviewed by the xCAT architects. Examples are changes to any of the existing common Perl library routines in the /svn/xcat/xcat-core/.../perl-xCAT/xCAT path.
- Addition of new xCAT plugins should be reviewed by the xCAT architects. The new plugin should adhere to the coding guidelines for xCAT plugins using the common utilities provided by xCAT (e.g. xCAT::MsgUtils, etc). See xCATWorld.pm and other plugins for examples.
- Packaging and Documentation changes should be request via a SourceForge Tracker request.
- Comment your code. A guideline of approximately 1 comment for every 10 lines of code is suggested. Huge block comments are not needed (not even wanted), just the useful info about what the code is doing, that is not immediately obvious from the code itself.
- Use good programming practices. Shouldn't even have to include this one, but:
- Use perl, unless there is a specific reason not to
- Use "use strict" in all files
- Handle all error cases
- See Programming Tips for more info
- Consider all platforms and environments when making your code changes. xCAT supports many environments, and most users only care about 1 or 2 of those environments. Thus, the tendency is for them to make code changes that work for their environment but make break other environments. Specifically, consider how your code change will function on AIX (if you are a linux xCAT user).
- Provide user documentation as part of the commit. Check in updates to the man pages, cookbooks, etc. Whatever is needed for users to know how to use this feature. If this is a new command, create the man page using pod. See Documentation Organization.
- Include a detailed comment in the commit command. This helps the xCAT architects understand what has been checked in and is also used in the changelog of the next release.
