Feed on Feeds Redux Developer Guidelines
----------------------------------------
The purpose of this document is to define procedures and naming conventions used in the FoF Redux CVS repository.

$Id: DEVELOPER_GUIDE,v 1.2 2005/12/23 17:07:11 nilspace Exp $

Branch Names
------------
Branch names are comprised of a branch base name plus the "-branch" extension.  Branch base names should be in all capitals and the underscore should be used as the word separator.

It is not required to use the underscore to separate every word.  It should be used where appropriate to keep the branch name descriptive and easily understandable.

The only exception to the "-branch" suffix rule applies to the HEAD branch.  It is a special branch built in to the CVS repository and therefore can not be renamed.  Because of this restriction, the HEAD branch name *and* base branch name are one in the same.

Short names for branches is discouraged. Because branches and tags must be globally unique, the names should be descriptive enough to avoid confusion with other branches or tags.

Examples:

SOME_FEATURE_TO_TEST-branch
FEEDREFACTOR-branch
TAGFEATURE-branch
MYREALLYKEWLHACK-branch           <---  not preferred. hard to read and shouldn't include a reference to a particular developer.(MY)


Tag Names
---------
Tag names should also follow the branch naming rules with the exception that tags must never have a "-branch" extension to them.  


Tags for branches
-----------------
There are specific tags that must be used to record significant points in a branch's lifecycle.
The significant points are:
* when the branch is created
* when changes from another branch are merged onto a branch
* when changes in a branch are merged onto another branch
* when a branch is closed

root of branch tag:  Before creating a branch, the point where the branch was created should be tagged.  The name must be the branch root name with "-root" appended to it.
  ex:  TAGFEATURE-root
  ex command:  cvs tag -r HEAD TAGFEATURE-root

merge tags:          
  All merge tags should follow the same format.
     <source branch>-<dest branch>-<date>-<tag suffix>
  The date is in the format: YYYYMMDD
  The tag suffix should be one of the following:  merge, premerge, postmerge
                     
  Before a merge is started, both branches involved in the merge should be tagged.
  The source branch should have a tag with the suffix 'merge'.
  The destination branch should have a tag with the suffix 'premerge'.
  Once the merge is completed and committed to the destination branch, the postmerge tag must be added to the destination branch.

end of branch tag:   
  When a branch is retired and should not be committed to anymore.  A tag should be put on the final revisions for that branch.  The name is the branch root name with "-close" appended.
  ex: TAGFEATURE-close
  ex command:  cvs tag -r TAGFEATURE-branch TAGFEATURE-close


Stable branches
---------------
The stable branch for a release must have the base name in the format: REL-<major>_<minor>.  Stable branches also use the -branch suffix
  ex:  REL-0_3-branch

Some restrictions related to stable branches:
* a stable branch is never the destination for a merge
* only bugfixes should be committed to a stable branch 


Tags for releases
-----------------
What is a release?  A release is a particular set of source revisions that are exported from the repository and packaged for distribution.  All releases must have a tag and the repository export must be made using that tag.  Using the release tag to export ensures consistent creation of the package. (tar file)

The tag name for a release will use the branch root name to which the tag is applied.  The tag name format is 
  <base branch name>_<patch level>_<quality identifier>

Patch level is a numeric count starting at 0 (zero).  The quality identifier is optional and should only be used early in the stable branch lifecycle to avoid the patch level increasing out of control.

Examples:
REL-0_2_0_beta1
REL-0_4_2_rc1
REL-0_8_3

Release tags without a quality identifier should be considered the highest or "most stable" revision for that patch level.


Developer snapshots
-------------------
Developer snapshots should also be tagged.  The tag name is similar to release tags but use a datestamp instead of a patch level/quality level.  The suffix for a snapshot should always be "-snapshot".  

Format:  <branch base name>-<date>-snapshot

Snapshots should be used for packages created from revisions on a development branch. (HEAD or others)
Snapshot tags on a stable branch is forbidden because those branches have their own special tags used for releases. (see above)

Examples:
HEAD-20051230-snapshot
TAGFEATURE-20060102-snapshot


General rules and CVS command examples
--------------------------------------

* major features and/or code changes should be put on their own branch while the code is stabilized.
* branching from a branch other than HEAD is forbidden. (I.E. only branch from head)