From 0cbd015aec07e51994f6e4e6de0cccde1b5ccb9d Mon Sep 17 00:00:00 2001 From: Brenton Leanhardt Date: Tue, 8 Jul 2008 10:59:34 -0400 Subject: Adding some release repo documentation --- genome-docs/genome-docs-1.0.0/en-US/Appendix.xml | 268 +++++++++++++++++++++++ genome-docs/genome-docs.spec | 2 +- 2 files changed, 269 insertions(+), 1 deletion(-) 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. + +
+ Managing releases with the &PRODUCT; tooling + + 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 subversion or + git the same discipline also + applies to configuration artifacts and binary + dependencies. + + + + For this reason, projects making use of the &PRODUCT; + tooling have the ability to track all content via + git repositories. Detailed + below is a process that handles bundling the state of + several puppet modules, RPM + dependencies and source code into one deliverable that + can be tracked throughout the project lifecycle. + + +
+ The "release" repository + + The release git + repository is basically just a + superproject + + which can + contain any number of + submodules. This allows + project dependencies to be woven together as + needed. + +
+ +
+ Creating a superproject + + A superproject is really just a normal git + repository for tracking the states of other + repositories. + +# Create a new git repository +mkdir release +cd release +git init + + + Once the repository has been created submodules can be added. + + +# Add the submodule +git submodule add [url] [path/in/superproject/to/be/created] + + + + At this point a new file will have been added + called .gitmodules. 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 + + 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 + git-submodule + manpage for more information. + + + + + Note + + See the + git-submodule + manpage for more information. + + + +
+ +
+ A word on pushing superprojects + + 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 + git push 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 genome-sync. + + +
+ +
+ Branching strategy + + 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. + + + + In a nutshell it conventions are: + + + + If a project is named + foo + then there will be a + branch called + foo + on all git repositories + touched by that project. + + + + + Branches that match the + project name are + considered to be stable + and "on their way to + production". + + + + + 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. + + + + 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. + + + + + If the fetch/checkout + process results in a + change, at the root of + the superproject + git + status + will reflect the + change. The changes + can then been commited + (on the superproject + branch that corresponds + to the project name). + + + + + + + Note + + These conventions only + need 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. + + +
+ +
+ What about the master branch? + + 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 + trunk and + master should be used. + The main exception with the &PRODUCT; toolings + is the case of the + puppet 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 + master branch. + + + The normal workflow for a + puppet + module is to test changes on the + master branch and + then push changes to the project branch + when they are baked. + + + Important + + 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. + + +
+
diff --git a/genome-docs/genome-docs.spec b/genome-docs/genome-docs.spec index eaad788..3402e44 100644 --- a/genome-docs/genome-docs.spec +++ b/genome-docs/genome-docs.spec @@ -1,6 +1,6 @@ Name: genome-docs Version: 1.0.0 -Release: 24%{?dist} +Release: 25%{?dist} Summary: Genome documentation Group: Applications/System -- cgit