Developer Guidelines
From SystemImager
Contents |
Developer Guidelines
Coding
- For perl code, read "man perlstyle", it's not very long, but is very insightful. I just read it recently myself, but it turns out that it describes the style I prefer almost to a tee (I wonder where that saying came from). Except for this one bit:
[Semicolon omitted in "short" one-line BLOCK.]
You can ignore that bit.
- Try to mimick the style of the code that you are working in, unless it's perl and it conflicts with the perlstyle man page. Not all of the existing perl code was written accordingly. This will significantly improve your chances of it being accepted.
- Include a usage statement with every function/subroutine, no matter how simple and self-explanatory that function is.
Example:
#
# Description:
# Chooses most appropriate from the available partition tools.
#
# Usage:
# my $partition_tool = which_partition_tool();
#
sub which_partition_tool {
[... code here ...]
}
- When you close a bug or feature request, add an appropriate line to the CHANGE.LOG that includes the bug or feature number and who you are.
- Always give people credit in the CREDITS file.
- Have fun!
Versioning
Synopsis
VERSION.MAJOR.MINOR[.EXTRAVERSION]
Official release
- SystemImager official releases are denoted using a standard triplet of integers: VERSION.MAJOR.MINOR.
- The basic intent is that a VERSION increment indicates a major architectural change, a MAJOR increment indicates major improvements and a MINOR increment indicates a bug fix release or a release with minor improvements.
- An odd MAJOR number indicates an unstable release, an even number indicates a stable release.
- An odd MINOR number indicates a pre-release or a release candidate (see below) of the VERSION.MAJOR.(MINOR + 1), an even number always indicates an official release (stable or unstable, depening on the MAJOR number).
- A pre-release is always considered unstable, even if MAJOR is a even number.
- Official releases are always distributed uploading the files and packages via the SourceForge file release system.
Development pre-release
- Development pre-release or release candidate versions use an additional integer at the end of the version string: VERSION.MAJOR.MINOR.EXTRAVERSION. By definition the EXTRAVERSION number can be appended only if the MINOR number is odd (pre-release or releaes candidate).
- The first 3 numbers (VERSION, MAJOR and MINOR) define the version of the next official release, that will be called: VERSION.MAJOR.(MINOR + 1).
- EXTRAVERSION should always contain the string svnNUMBER, where NUMBER is a reference to the original SVN version (checked into http://svn.systemimager.org). By default a pre-release is always based on the exact content of the SVN branch MAJOR.MINOR.x. Otherwise an additional comment, string, abbreviation, etc. must be appended, that can identify for example:
- the name of the developer (i.e. .svn4040arighi),
- an explicative name of a new feature present only in the local repository of a developer (i.e. svn3636bittorrent),
- a name that identify the origin of the source repository (i.e. .svn3636trunk, .svn3636udevbranch, etc.).
Examples
- Stable mainline:
- 3.8.0
- 3.8.2
- 3.8.4
- ...
- Unstable:
- 3.9.0
- 3.9.2
- 3.9.4
- ...
- Pre-release:
- 3.9.1.svn4100 = pre-release of 3.9.2 (based on SVN version 4100)
- 3.8.3.svn4300 = pre-release of 3.8.4 (based on SVN version 4300)
- 3.9.5.svn5136veryexperimentalfeature = pre-release of 3.9.6 (based on SVN version 5136 + adds the new cool "veryexperimentalfeature" that is not yet checked in the svn repository)
- 3.8.5.svn5050arighi = pre-release of 3.8.6 (based on SVN version 5050 + customizations added by the developer arighi, not yet checked in the svn repository)
SVN
- The current development branch is always tagged "trunk". It is intended for feature additions and funky stuff. Unless you're just fixing a bug, or updating the stable documentation, this is what you want.
- The stable branch and unstable branch are always called: VERSION.MAJOR.x
- The stable branch is only to be used for fixing bugs.
- Only Brian Finley or Andrea Righi will modify SVN tags of any kind, such as for versioning releases or creating development branches.
Checkout Steps for Developers
MY_USERNAME=finley
Development trunk:
svn checkout svn+ssh://$MY_USERNAME@svn.systemimager.org/var/lib/svn/systemimager/trunk si.trunk/
A particular revision of the development trunk:
REVISION=3256 svn checkout -r $REVISION svn+ssh://$MY_USERNAME@svn.systemimager.org/var/lib/svn/systemimager/trunk si.$REVISION/
A particular branch:
BRANCH=3.4.x svn checkout svn+ssh://$MY_USERNAME@svn.systemimager.org/var/lib/svn/systemimager/branches/$BRANCH si.$BRANCH/
Submitting patches
Select e-mail destination
Always send your patches to sisuite-devel@lists.sourceforge.net.
Separate logical changes
If your changes include multiple bug fixes and performance enhancements, separate those changes into two or more patches.
On the other hand, if you make a single change to numerous files, group those changes into a single patch. Thus a single logical change is contained within a single patch.
If one patch depends on another patch in order for a change to be complete, that is OK. Simply note "this patch depends on patch X" in your patch description.
If you cannot condense your patch set into a smaller set of patches, then only post say 15 or so at a time and wait for review and integration.
Email subject format
Use the following template for the subject of your email with a patch:
[PATCH] one-line summary
Where "one-line summary" summarizes the change the patch makes. This summary is copied directly into the svn changelog, so make sure that your summary is descriptive. "update to latest SVN" or "fix bug" is not specific enough about what portion of the code is being modified.
Keep your overall subject line under 65 characters or so.
Email body contents: description
At the beginning of your email, use as many lines as you wish to describe the patch. This text is copied directly into the SVN changelog.
Be as specific as possible. The WORST descriptions possible include things like "update Server.pm", "bug fix for Server.pm", or "this patch includes updates for the server side. Please apply."
If your description starts to get too long, that's a sign that you probably need to split up your patch.
Include comments you don't wish to be in the SVN changelog following a "---" terminator line. The terminator must be on a line by itself.
Name your SystemImager version
It is important to note, either in the subject line or in the patch description, the SystemImager version to which this patch applies.
If the patch does not apply cleanly to the latest SystemImager version, it will reduce the chances of your change being accepted.
Email body contents: patch
Always uses "diff -urN" to create patches. When creating your patch, make sure to create it in "unified diff" format, as supplied by the '-u' argument to diff(1).
Patches should be based in the root SystemImager source directory, not in any lower subdirectory.
To create a patch for a single file, it is often sufficient to do:
SRCTREE=systemimager-3.9.6
MYFILE=lib/SystemImager/Server.pm
cd $SRCTREE
cp $MYFILE $MYFILE.orig
vi $MYFILE # make your change
cd ..
diff -u $SRCTREE/$MYFILE{.orig,} > /tmp/patch
To create a patch for multiple files, you should unpack a "vanilla", or unmodified SystemImager source tree, and generate a diff against your own source tree. For example:
MYSRC=/devel/systemimager-3.9.6
tar xvjf systemimager-3.9.6.tar.bz2
mv systemimager-3.9.6 systemimager-3.9.6-vanilla
diff -urN systemimager-3.9.6-vanilla $MYSRC > /tmp/patch
Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch after generated it with diff(1), to ensure accuracy.
The format of the patches made by SVN is compliant with these rules.
If your changes produce a lot of deltas, you may want to look into splitting them into individual patches which modify things in logical stages. This will facilitate easier reviewing by other SystemImager developers, very important if you want your patch accepted.
E-mail size
Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 40 kB in size, it is preferred that you store your patch on an Internet-accessible server, and provide instead a URL (link) pointing to your patch.
No MIME, no links, no compression, no attachments: just plain text
It is important to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of your code.
For this reason, all patches should be submitting e-mail "inline".
WARNING: Be wary of your editor's word-wrap corrupting your patch, if you choose to cut-n-paste your patch.
Do not attach the patch as a MIME attachment, compressed or not. Many popular e-mail applications will not always transmit a MIME attachment as plain text, making it impossible to comment on your code.
