Adding some release repo documentation

1 files changed, 268 insertions, 0 deletions

diff --git a/genome-docs/genome-docs-1.0.0/en-US/Appendix.xml b/genome-docs/genome-docs-1.0.0/en-US/Appendix.xml
index 0af7cbd..04c3a9a 100644
--- a/genome-docs/genome-docs-1.0.0/en-US/Appendix.xml
+++ b/genome-docs/genome-docs-1.0.0/en-US/Appendix.xml
@@ -21,4 +21,272 @@
 			in.
 		</para>
 	</section>
+
+	<section id="genome-release"> 
+		<title>Managing releases with the &PRODUCT; tooling</title>
+		<para>
+			One of the challenges of working on large teams is
+			simply keeping track of all the various forms of
+			content that make up a project.  While teams have
+			traditionally used some sort of Source Code Management
+			tool such as <application>subversion</application> or
+			<application>git</application> the same discipline also
+			applies to configuration artifacts and binary
+			dependencies.
+		</para>
+
+		<para>
+			For this reason, projects making use of the &PRODUCT;
+			tooling have the ability to track all content via
+			<application>git</application> repositories.  Detailed
+			below is a process that handles bundling the state of
+			several <application>puppet</application> modules, RPM
+			dependencies and source code into one deliverable that
+			can be tracked throughout the project lifecycle.
+		</para>
+
+		<section id="genome-release-repo">
+			<title>The "release" repository</title>
+			<para>
+				The release <application>git</application>
+				repository is basically just a
+				<ulink
+					url="http://git.or.cz/gitwiki/GitSubmoduleTutorial"><emphasis>superproject</emphasis>
+				</ulink>
+				 which can
+				contain any number of
+				<emphasis>submodules</emphasis>.  This allows
+				project dependencies to be woven together as
+				needed.
+			</para>
+		</section>
+
+		<section id="genome-release-repo-usage">
+			<title>Creating a superproject</title>
+			<para>
+				A superproject is really just a normal git
+				repository for tracking the states of other
+				repositories.  
+				<screen>
+# Create a new git repository
+mkdir release
+cd release
+git init
+				</screen>
+
+				Once the repository has been created submodules can be added.
+
+				<screen>
+# Add the submodule
+git submodule add [url] [path/in/superproject/to/be/created]
+
+				</screen>
+
+				At this point a new file will have been added
+				called <filename>.gitmodules</filename>.  This
+				is the submodule configuration file.  Another
+				"file" that is created is a pseudofile that
+				corresponds to the path created when the
+				submodule was added.  Both of these should be
+				committed.
+
+				<important>
+					<title>Important</title>
+					<para>
+						The url used when adding the
+						submodule can be relative.
+						This is often more desirable
+						than hard coding the path to a
+						specific repository.  The main
+						reason is that the content
+						referenced by a particular
+						release repository should
+						actually exist in the Repo
+						Appliance.  This is a best
+						practice that allows Repo
+						Appliance state to be backed up
+						with the guarantee that a
+						project's state can be rebuilt
+						and the machines involved can
+						be provisioned.  
+						See the
+						<emphasis>git-submodule</emphasis>
+						manpage for more information.
+					</para>
+				</important>
+
+				<note>
+					<title>Note</title>
+					<para>
+						See the
+						<emphasis>git-submodule</emphasis>
+						manpage for more information.
+					</para>
+				</note>
+			</para>
+		</section>
+
+		<section>
+			<title>A word on pushing superprojects</title>
+			<para>
+				Typically only metadata is stored in the
+				release superproject.  For this reason copying
+				release deliverables from one Repo Appliance to
+				another is not as simple as using
+				<userinput>git push</userinput> on only the
+				release repository.  If relative submodule
+				paths are used (and they should be) the state
+				referenced in all submodules must exist on a
+				given Repo Appliance.  Luckily, this is quite
+				easy to do with <link
+					linkend="genome-sync">genome-sync</link>.
+			</para>
+
+		</section>
+
+		<section>
+			<title>Branching strategy</title>
+			<para>
+			      Complexity, risk as well as external factors all
+			      play a large role in how a particular project
+			      decides to branch.  Conventions go a long way to
+			      simplifying this process and can make projects
+			      move smoothly from development to production.
+			</para>
+
+			<para>
+				In a nutshell it conventions are:
+				<itemizedlist>
+					<listitem>
+						<para>
+							If a project is named
+							<emphasis>foo</emphasis>
+							then there will be a
+							branch called
+							<emphasis>foo</emphasis>
+							on all git repositories
+							touched by that project.
+						</para>
+					</listitem>
+					<listitem>
+						<para>
+							Branches that match the
+							project name are
+							considered to be stable
+							and "on their way to
+							production".  
+						</para>
+					</listitem>
+					<listitem>
+						<para>
+							Using the release
+							superproject is simply a
+							matter of wiring up the
+							branches for a
+							particular project into
+							one branch, which also
+							bears the name of the
+							project.
+						</para>
+
+						<para>
+							In practice what this
+							equates to is, after
+							adding the submodules
+							to a superproject,
+							going into the
+							submodule's directory
+							and getting the working
+							directory to match the
+							desired state.  If the
+							project branch naming
+							conventions are being
+							followed the content
+							can simply be fetched
+							and then checked out.  
+
+						</para>
+
+						<para>
+							If the fetch/checkout
+							process results in a
+							change, at the root of
+							the superproject
+							<userinput>git
+								status</userinput>
+							will reflect the
+							change.  The changes
+							can then been commited
+							(on the superproject
+							branch that corresponds
+							to the project name).
+						</para>
+					</listitem>
+				</itemizedlist>
+			</para>
+
+			<note>
+				<title>Note</title>
+				<para>
+					These conventions only
+					<emphasis>need</emphasis> to be
+					followed at the by the people who are
+					"interfaces" between teams.  The use of
+					Repo Appliances can also aid the
+					branching strategy in that it allows
+					each group to determine what works best
+					for them.  For example, development and
+					release engineering (RE) teams have
+					different goals when it comes to
+					managing a codebase.  In development a
+					team will be more concerned with how to
+					balance the bugfix and feature streams
+					of a project while RE will focus more
+					on how moving these changes through
+					the various environments affects other
+					projects.
+				</para>
+			</note>
+		</section>
+
+		<section>
+			<title>What about the master branch?</title>
+			<para>
+				For most git repositories it really isn't even
+				needed and only aids to confusion since there
+				is no consensus as to how branches like
+				<emphasis>trunk</emphasis> and
+				<emphasis>master</emphasis> should be used.
+				The main exception with the &PRODUCT; toolings
+				is the case of the
+				<application>puppet</application> module
+				repositories.  The hook that checks out the
+				module code and puts it on the modulepath needs
+				to know the name of a particular branch to work
+				with.  That branch is the
+				<emphasis>master</emphasis> branch.
+			</para>
+			<para>
+				The normal workflow for a
+				<application>puppet</application>
+				module is to test changes on the
+				<emphasis>master</emphasis> branch and
+				then push changes to the project branch
+				when they are baked.   
+			</para>
+			<important>
+				<title>Important</title>
+				<para>
+					This process can be followed regardless
+					of where in the lifecycle the change
+					occurs.  Development can test their
+					changes, push to their project branch
+					and then QA can push the project branch
+					into their master.  Once through QA,
+					the code can again be pushed to a
+					project branch where RE can take over.
+				</para>
+			</important>
+		</section>
+	</section>
 </appendix>