From 9954232a9b160846113c8375d590d5c3fd3a0bcf Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Mar 10 2011 01:36:22 +0000 Subject: Update repository documentation manual. --- diff --git a/Manual/Filesystem/branches.texi b/Manual/Filesystem/branches.texi index b2ea441..527be6d 100755 --- a/Manual/Filesystem/branches.texi +++ b/Manual/Filesystem/branches.texi @@ -11,57 +11,89 @@ structure. @subsection Usage -If changes committed to the main develpment line are all predictable -(e.g., there is just one person committing changes), there is no a big -need of using @file{branches/} directory structure, in this case we -can go straight from @file{trunk/} to @file{tags/}. However, when -there is no way to predict changes in the main development directory -structure (e.g., there are many people working at it at the same time) -it is required to find out a space when changes can occur in -predictable ways. +If changes committed up to the main develpment line are all +predictable (e.g., there is just one person committing changes), there +is no a big need of using @file{branches/} directory structure, in +this case we can go straight from @file{trunk/} to @file{tags/}. +However, when there is no way to predict changes in the main +development line (e.g., there are many people working at it at the +same time) it is needed to find out a different place for changes to +occur in more predictable ways. -At this point several options may arise to work with branches. Let's -see a few ones: +At this point, several options may arise to create branches. In the +CentOS Artwork Repository we prefer to use the idea of separating the +main development line into different major development lines whose +receive frequent update in a fixed period of time. In this +configuration, a major development line is a directory structure +branched from @file{trunk/} directory structure. That is, we take a +functional instance of @file{trunk/} directory structure and store it +under @file{branches/} directory structure using a branch identifier +and the same hierarchy the main development line uses. -@subsubsection Temporal Branch +When we create separete development lines, this way, we are creating a +major development line that will receive minor updates to current +functionalities but won't introduce new functionalities nor remove old +ones. This is very importat if you need to have a predictable +behaviour for that branch content through a period of time. When that +period of time is gone, a new major development line is created to +introduce new functionalities from @file{trunk/} directory structure +and so repeating the whole production cycle. -The branched directory is created temporaly to fix a problem and when -it is done, it is merged back into @file{trunk/} directory structure -and removed from the repository. +In order to create branches inside the CentOS Artwork Repository the +whole repository structure must be considered. This is because all +directory structures stored under @file{trunk/} directory structure +are connected among themselves. This way, we create branches for the +whole @file{trunk/} directory structure and never to individual +components inside it. On the other hand, creating branches for the +whole @file{trunk/} directory structure duplicates lots of files and +demands a considerable amount of storage space which is not +convenient. As an intermediate solution, we do not create branches for +the @file{trunk/Identity/} directory structure, but the +@file{trunk/Manual}, @file{trunk/Scripts} and @file{trunk/Locales} +directory structures only. This way, we create documentation, +automation scripts and locale information for specific revisions of +@file{turnk/Identity} directory structure. -@subsubsection Major Release Branch +A good reason to create a major development line could be +documentation. Consider how hard it could be build a documentation +manual if the target of it is changing unpredictably; what are we +documenting? Something similar happens with @command{centos-art} +command-line, if the directory structure the @command{centos-art} was +design to work with changes unexpectedly it is very hard to implement +a path-based functionality in that environment; where are we retriving +files from or saving them to? -The branched directory is created to implement the concept of major -release. In this configuration we frequently take a functional -instance of @file{trunk/} directory structure and create branch for -it. While @file{trunk/} directory structure can receive new -functionalities or remove old ones, the branched instance of it does -not. The branched instance can receive updates for available files -only but not introduce new ones or remove old ones as it is done in -@file{trunk/} directory structure. +Assuming there is no way to predict changes in main development line, +the creation of new @file{branches} inside the CentOS Artwork +Repository uses The CentOS Project Release Schema. This is, a new +major development line is created every 2 years using @file{trunk/} +directory structure as reference. Each major development line is +updated regulary in order to create frozen lines under @file{tags/} +directory structure every 6 months. -The frequency each branched directory is created depends on how long -can the branched directory could be on its state before consider it as -dated and also the time we want to provide it as stable for everyone -to use as expected. The exact time depends on the sort of information -such branched directory structure contains. +@image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-1,400pt} -To illustrate this concept consider the @file{trunk/Scripts/Bash/Cli} -directory structure. This directory contains the main development line -of @command{centos-art} command-line internface. If there are several -people working on it and you find a problem in it, it could be very -frustrating for you try to solve it in an environment when other -changes could be introduced unexpectedly, specially if such change you -need to do is considerable long. For that reasing it is much better to -commit small changes frequently to fix small things, but if you -absolutly need to make a long change (e.g., you want to implement a -new functionality) it is necessary you create branch of @file{trunk/} -directory structure (or any other branch or tag already created) to be -on the safe side while you implement your functionality. +The updates commited up to individual major development lines need to +be merged into the @file{trunk/} directory structure in order for +further major development lines to benefit from previous major +development lines improvements. The appropriate moment to commit from +major development lines to @file{trunk/} directory structure is when +the frozen line of a major development line is been created. This +way, the main development line is the central place for changes, a +place to concentrate changes from different major development lines +that may be or not being developed at the same time. -In order to keep branch creation organized, we use the @file{trunk} -directory structure as reference and add a numerical identifier to the -end of the path that increments one unit for each branch created. +As general convenction, when a new major development line is created, +functionalities from previous major development lines are included +into the new development line. However, improvements for components +included from previous major development lines are not handled inside +the new major development line which imported them. Such improvements +are handled by the previous development line and merged up to main +development line to improve the main development line, in the same way +the new major development line merges the improvements of the new +functionalities it was created for. As final resault, both changes +merged from new and previous major development lines will be included +into the next major development line. @subsection See also diff --git a/Manual/repository-html/repository.html b/Manual/repository-html/repository.html index 3df0d7d..f8f7a91 100644 --- a/Manual/repository-html/repository.html +++ b/Manual/repository-html/repository.html @@ -12,7 +12,7 @@ Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License. --> - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - +