
@file doc/CheckInTests
@brief Document check-in acceptance tests for fedfs-utils

Copyright 2011 Oracle.  All rights reserved.

This file is part of fedfs-utils.

fedfs-utils is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2.0 as
published by the Free Software Foundation.

fedfs-utils is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License version 2.0 for more details.

You should have received a copy of the GNU General Public License
version 2.0 along with fedfs-utils.  If not, see:

	http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt


Introduction
------------

This document outlines basic policy guidelines for participating in the
fedfs-utils development effort.


Submitting patches
------------------

I'm a stickler for good patch descriptions.  Often the description is
the only documentation we have when looking back at what was done a
year ago or longer.  Some tips:

 o  Make the description clear and painfully obvious
 o  Provide root cause analysis
 o  Provide links to bug reports
 o  Don't be afraid to list lessons learned
 o  For bug fixes, list the commit that introduced the problem
 o  Indicate whether behavior changes, or if the patch is only clean-up
 o  List possible security implications
 o  Mention testing that has been done, or that can be done in the future
 o  Spell out rationale for any exceptions to guidelines in this document
 o  Always justify complexity or changes to APIs and ABIs

In other words, don't assume ANY context from previous e-mail or personal
conversations that occurred while a patch was being constructed.

fedfs-utils adopts much precedent set by Linux kernel developers:

  http://kernelnewbies.org/UpstreamMerge/SubmittingPatches

Especially:

 o  Use "diff -uprN"
 o  Carefully describe why the change is needed
 o  Separate logical changes
 o  No MIME, no links, no compression or attachments.  Just plain text e-mail
 o  Sign your work -- sections 12, 13, and 14 -- these are key

See also Documentation/CodingStyle in the Linux kernel source tree.

Please ensure you have the right to submit the patches you send.  If
you create changes at work, your employer may own the patch.
Submitted patches fall under the GPLv2 once they are merged.


Review
------

This is an open source project, so design and code review are a key part
of the development process.  Patches are posted for review on
<fedfs-utils-devel@oss.oracle.com> and can be tracked via a patchwork
repository at http://patchwork.ozlabs.org/project/fedfs-utils/list/ .

Before commits become a permanent part of the source control history,
time-limited review is performed on the above mailing list.


Per-commit acceptance tests
---------------------------

This is basic stuff that's easy to run, and should be working for
bisecting to be useful.

 1.  "autogen.sh" must run without error
 2.  "CC=cgcc ./configure --enable-silent-rules --exec=/usr" must
     complete successfully
 3.  "make -s -j3" must complete without error or new compiler
     or sparse warnings
 4.  "make doxy" must complete with no errors or warnings
 5.  "make covbuild" must complete with at least 85% compilation
     units ready for analysis
 6.  "make distcheck" must complete without error
 7.  "make distclean" must complete without error
 8.  "git status" must produce no output on a clean tree
 9.  "git clean -d -f -x" does not break anything
10.  "git log -p" shows no new white space damage

To preserve bisectability, the tree MUST build after each commit.

Try to maintain documentation coherency with code.  Check code against
man pages and the INSTALL and README documents.

Python components must comply with PEP 8 and must run correctly under
Python 2.7+ and 3.  A commit must not introduce any new pylint warnings
or errors.

At some point, we'd like:

 1.  Automated checking of coding style and white space
 2.  Automated fortify or splint testing during check-in
 3.  Automated unit tests


Per-release
-----------

 Release numbering:

        <major>.<minor>[.<maint>[.<bugfix>]]

 Major releases introduce new features, and may not always be backwards
 compatible with earlier releases.  Minor releases may introduce new
 features, but will be backwards compatible with earlier minor releases
 with the same major version number.

 While we are in alpha, that last rule may be bent somewhat.

 Maintenance releases are generally for bug fixes and security patches.
 New feature development occurs in major and minor releases.

 Release candidate:

 One or more release candidates will be provided before each minor and
 major release.

 Acceptance:

  1. All per-commit acceptance tests must pass
  2. Integration testing (run everything with simple use cases)
  3. Comment period:
	* Major release candiate: three weeks
	* Minor release candidate: two weeks
	* Maintenance release candidate: three to five days

 Push:

  1. Update README and/or release notes
  2. Update package version in configure.ac
  3. Update sonumber of shared libraries (as needed)
  4. Create a commit for the release
  5. Create a tag for the release commit
  6. gc the git database and push the release
  7. "make distclean; sh ./autogen.sh; ./configure"
  8. "make distcheck" and publish the tarball

