Blame Manual/repository-html/repository_61.html

ee1f37
ee1f37
<html>
d1db00
d1db00
organization, and administration of CentOS Artwork Repository.
d1db00
d1db00
Copyright C 2009-2011 Alain Reguera Delgado
ee1f37
ee1f37
Permission is granted to copy, distribute and/or modify this document
ee1f37
under the terms of the GNU Free Documentation License, Version 1.2 or
ee1f37
any later version published by the Free Software Foundation; with no
ee1f37
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
ee1f37
copy of the license is included in the section entitled GNU Free
ee1f37
Documentation License.  
ee1f37
-->
406f69
ee1f37
ee1f37
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
ee1f37
            Karl Berry  <karl@freefriends.org>
ee1f37
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
ee1f37
            and many others.
ee1f37
Maintained by: Many creative people <dev@texi2html.cvshome.org>
ee1f37
Send bugs and suggestions to <users@texi2html.cvshome.org>
ee1f37
ee1f37
-->
ee1f37
<head>
671838
<title>CentOS Artwork Repository: 2.57 The trunk/Scripts/Bash/Cli/Functions/Path Directory</title>
ee1f37
671838
<meta name="description" content="CentOS Artwork Repository: 2.57 The trunk/Scripts/Bash/Cli/Functions/Path Directory">
671838
<meta name="keywords" content="CentOS Artwork Repository: 2.57 The trunk/Scripts/Bash/Cli/Functions/Path Directory">
ee1f37
<meta name="resource-type" content="document">
ee1f37
<meta name="distribution" content="global">
ee1f37
<meta name="Generator" content="texi2html 1.76">
ee1f37
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
ee1f37
<style type="text/css">
ee1f37
ee1f37
@import "/home/centos/artwork/trunk/Identity/Models/Css/Texi2html/common.css";
ee1f37
ee1f37
a.summary-letter {text-decoration: none}
ee1f37
pre.display {font-family: serif}
ee1f37
pre.format {font-family: serif}
ee1f37
pre.menu-comment {font-family: serif}
ee1f37
pre.menu-preformatted {font-family: serif}
ee1f37
pre.smalldisplay {font-family: serif; font-size: smaller}
ee1f37
pre.smallexample {font-size: smaller}
ee1f37
pre.smallformat {font-family: serif; font-size: smaller}
ee1f37
pre.smalllisp {font-size: smaller}
ee1f37
span.sansserif {font-family:sans-serif; font-weight:normal;}
ee1f37
ul.toc {list-style: none}
ee1f37
-->
ee1f37
</style>
ee1f37
ee1f37
ee1f37
</head>
ee1f37
ee1f37
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
ee1f37
ee1f37
671838
[ < ]
671838
[ > ]
ee1f37
   
671838
[ << ]
671838
[ Up ]
671838
[ >> ]
ee1f37
   
ee1f37
   
ee1f37
   
ee1f37
   
56a476
[Top]
56a476
[Contents]
671838
[Index]
56a476
[ ? ]
ee1f37
671838
671838
671838

2.57 The <tt>`trunk/Scripts/Bash/Cli/Functions/Path'</tt> Directory

671838
671838
671838
671838

2.57.1 Goals

671838
671838

This section exists to organize files related to path

671838
functiontionality.  The path functionality standardizes
671838
movement, syncronization, branching, tagging, and general file
671838
maintainance inside the repository. 
671838

671838
671838
671838

2.57.2 Description

671838
671838

"CentOS like trees, has roots, trunk, branches, leaves and

671838
flowers.  Day by day they work together in freedom, ruled by the laws
671838
of nature and open standards, to show the beauty of its existence."
671838

671838
671838
671838

2.57.2.1 Repository layout

671838
671838

The repository layout describes organization of files and directories

671838
inside the repository. The repository layout provides the standard
671838
backend required for automation scripts to work correctly. If such
671838
layout changes unexpectedly, automation scripts may confuse themselves
671838
and stop doing what we expect from them to do.
671838

671838

As convenction, inside CentOS Artwork Repository, we organize files

671838
and directories related to CentOS corporate visual identity under
671838
three top level directories named: <tt>`trunk/'</tt>, <tt>`branches/'</tt>,
671838
and <tt>`tags/'</tt>. 
671838

671838

The <tt>`trunk/'</tt> directory (see section The <tt>`trunk'</tt> Directory) organizes the main

671838
development line of CentOS corporate visual identity. Inside
671838
<tt>`trunk/'</tt> directory structure, the CentOS corporate visual
671838
identity concepts are implemented using directories.  There is one
671838
directory level for each relevant concept inside the repository. The
671838
<tt>`trunk/'</tt> directory structure is mainly used to perform
671838
development tasks related to CentOS corporate visual identity.
671838

671838

The <tt>`branches/'</tt> directory () oranizes

671838
parallel development lines to <tt>`trunk/'</tt> directory. The
671838
<tt>`branches/'</tt> directory is used to set points in time where
671838
develpment lines are devided one from another taking separte and
671838
idependent lives that share a common past from the point they were
671838
devided on. The <tt>`branches/'</tt> directory is mainly used to perform
671838
quality assurance tasks related to CentOS corporate visual identity.
671838

671838

The <tt>`tags/'</tt> directory (see section The <tt>`tags'</tt> Directory) organizes parallel frozen

671838
lines to <tt>`branches/'</tt> directory.  The parallel frozen lines are
671838
immutable, nothing change inside them once they has been created.  The
671838
<tt>`tags/'</tt> directory is mainly used to publish final releases of
671838
CentOS corporate visual identity.
671838

671838

The CentOS Artwork Repository layout is firmly grounded on a

671838
Subversion base.  Subversion (http://subversion.tigris.org) is a
671838
version control system, which allows you to keep old versions of files
671838
and directories (usually source code), keep a log of who, when, and
671838
why changes occurred, etc., like CVS, RCS or SCCS.  Subversion keeps a
671838
single copy of the master sources.  This copy  is called the source
671838
"repository"; it contains all the information to permit extracting
671838
previous versions of those files at any time.
671838

671838
063806
671838

2.57.2.2 Repository name convenctions

b9dbd3
671838

Repository name convenctions help us to maintain consistency of names

671838
inside the repository.
671838

671838

Repository name convenctions are applied to files and directories

671838
inside the repository layout. As convenction, inside the repository
671838
layout, file names are all written in lowercase
671838
(<samp>`01-welcome.png'</samp>, <samp>`splash.png'</samp>, <samp>`anaconda_header.png'</samp>,
671838
etc.) and directory names are all written capitalized (e.g.,
671838
<samp>`Identity'</samp>, <samp>`Themes'</samp>, <samp>`Motifs'</samp>, <samp>`TreeFlower'</samp>,
671838
etc.).
671838

671838

Repository name convenctions are implemented inside the

671838
cli_getRepoName function of <tt>`centos-art.sh'</tt> script. With
671838
cli_getRepoName function we reduce the amount of commands and
671838
convenctions to remember, concentrating them in just one single place
671838
to look for fixes and improvements.
671838

b9dbd3
063806
671838

2.57.2.3 Repository work flow

b9dbd3
671838

Repository work flow describes the steps and time intervals used to

671838
produce CentOS corporate visual identity inside CentOS Artwork
671838
Repository.  
671838

671838

To illustrate repository work flow let's consider themes' development

671838
cycle. 
671838

671838

Initially, we start working themes on their trunk development line

671838
(e.g., <tt>`trunk/Identity/Themes/Motifs/TreeFlower/'</tt>), here we
671838
organize information that cannot be produced automatically (i.e.,
671838
background images, concepts, color information, screenshots, etc.).
671838

671838

Later, when theme trunk development line is considered "ready" for

671838
implementation (e.g.,  all required backgrounds have been designed),
671838
we create a branch for it (e.g.,
671838
<tt>`branches/Identity/Themes/Motifs/TreeFlower/1/'</tt>).  Once the
671838
branch has been created, we forget that branch and continue working
671838
the trunk development line while others (e.g., an artwork quality
671838
assurance team) test the new branch for tunning it up. 
671838

671838

Once the branch has been tunned up, and considered "ready" for

671838
release, it is freezed under <tt>`tags/'</tt> directory (e.g.,
671838
<tt>`tags/Identity/Themes/Motifs/TreeFower/1.0/'</tt>) for packagers,
671838
webmasters, promoters, and anyone who needs images from that CentOS
671838
theme the tag was created for.
671838

671838

Both branches and tags, inside CentOS Artwork Repository, use

671838
numerical values to identify themselves under the same location.
671838
Branches start at one (i.e., <samp>`1'</samp>) and increment one unit for each
671838
branch created from the same trunk development line.  Tags start at
671838
zero (i.e., <samp>`0'</samp>) and increment one unit for each tag created from
671838
the same branch development line.
671838

671838
Convenction

Convenction

Do not freeze trunk development lines using tags

671838
directly.  If you think you need to freeze a trunk development line,
671838
create a branch for it and then freeze that branch instead.
671838

b9dbd3
671838

The trunk development line may introduce problems we cannot see

671838
immediatly. Certainly, the high changable nature of trunk development
671838
line complicates finding and fixing such problems. On the other hand,
671838
the branched development lines provide a more predictable area where
671838
only fixes/corrections to current content are commited up to
671838
repository. 
671838

671838

If others find and fix bugs inside the branched development line, we

671838
could merge such changes/experiences back to trunk development line
671838
(not visversa) in order for future branches, created from trunk, to
671838
benefit.
671838

671838

Time intervals used to create branches and tags may vary, just as

671838
different needs may arrive. For example, consider the release schema
671838
of CentOS distribution: one major release every 2 years, security
671838
updates every 6 months, support for 7 years long. Each time a CentOS
671838
distribution is released, specially if it is a major release, there is
671838
a theme need in order to cover CentOS distribution artwork
671838
requirements. At this point, is where CentOS Artwork Repository comes
671838
up to scene. 
671838

671838

Before releasing a new major release of CentOS distribution we create

671838
a branch for one of several theme development lines available inside
671838
the CentOS Artwork Repository, perform quality assurance on it, and
671838
later, freeze that branch using tags. Once a the theme branch has been
671838
frozen (under <tt>`tags/'</tt> directory), CentOS Packagers (the persons
671838
whom build CentOS distribution) can use that frozen branch as source
671838
location to fulfill CentOS distribution artwork needs. The same
671838
applies to CentOS Webmasters (the persons whom build CentOS websites),
671838
and any other visual manifestation required by the project.
671838

b9dbd3
063806
671838

2.57.2.4 Parallel directories

b9dbd3
671838

Inside CentOS Artwork Repository, parallel directories are simple

671838
directory entries built from a common parent directory and placed in a
671838
location different to that, the common parent directory is placed on.
671838
Parallel directories are useful to create branches, tags,
671838
translations, documentation, pre-rendering configuration script, and
671838
similar directory structures.
671838

671838

Parallel directories take their structure from one unique parent

671838
directory. Inside CentOS Artwork Repository, this unique parent
671838
directory is under <tt>`trunk/Identity'</tt> location.  The
671838
<tt>`trunk/Identity'</tt> location must be considered the reference for
671838
whatever information you plan to create inside the repository.
671838

671838

In some circumstances, parallel directories may be created removing

671838
uncommon information from their paths. Uncommon path information
671838
refers to those directory levels in the path which are not common for
671838
other parallel directories.  For example, when rendering
671838
<tt>`trunk/Identity/Themes/Motifs/TreeFlower/Distro'</tt> directory
671838
structure, the <tt>`centos-art.sh'</tt> script removes the
671838
<tt>`Motifs/TreeFlower/'</tt> directory levels from path, in order to
671838
build the parallel directory used to retrived translations, and
671838
pre-rendering configuration scripts required by render
671838
functionality.
671838

671838

Another example of parallel directory is the documentation structure

671838
created by manual functionality. This time,
671838
<tt>`centos-art.sh'</tt> script uses parallel directory information with
671838
uncommon directory levels to build the documentation entry required by
671838
Texinfo documentation system, inside the repository.
671838

671838

Othertimes, parallel directories may add uncommon information to their

671838
paths. This is the case we use to create branches and tags. When we
671838
create branches and tags, a numerical identifier is added to parallel
671838
directory structure path. The place where the numerical identifier is
671838
set on is relevant to corporate visual identity structure and should
671838
be carefully considered where it will be.
671838

671838

When one parent directory changes, all their related parallel

671838
directories need to be changed too. This is required in order for
671838
parallel directories to retain their relation with the parent
671838
directory structure.  In the other hand, parallel directories should
671838
never be modified under no reason but to satisfy the relation to their
671838
parent directory structure.  Liberal change of parallel directories
671838
may suppresses the conceptual idea they were initially created for;
671838
and certainly, things may stop working the way they should do.
671838

b130a0
063806
671838

2.57.2.5 Syncronizing path information

b9dbd3
671838

Parallel directories are very useful to keep repository organized but

671838
introduce some complications.  For instance, consider what would
671838
happen to functionalities like manual (<samp>`trunk Scripts Bash
671838
Functions Manual'</samp>) that rely on parent directory structures to create
671838
documentation entries (using parallel directory structures) if one of
671838
those parent directory structures suddenly changes after the
671838
documentation entry has been already created for it? 
671838

671838

In such cases, functionalities like manual may confuse

671838
themselves if path information is not updated to reflect the relation
671838
with its parent directory.  Such functionalities work with parent
671838
directory structure as reference; if a parent directory changes, the
671838
functionalities dont't even note it because they work with the last
671838
parent directory structure available in the repository, no matter what
671838
it is. 
671838

671838

In the specific case of documentation (the manual

671838
functionality), the problem mentioned above provokes that older parent
671838
directories, already documented, remain inside documentation directory
671838
structures as long as you get your hands into the documentation
671838
directory structure (<tt>`trunk/Manuals'</tt>) and change what must be
671838
changed to match the new parent directory structure.
671838

671838

There is no immediate way for manual, and similar

671838
functionalities that use parent directories as reference, to know when
671838
and how directory movements take place inside the repository. Such
671838
information is available only when the file movement itself takes
671838
place inside the repository. So, is there, at the moment of moving
671838
files, when we need to syncronize parallel directories with their
671838
unique parent directory structure.
671838

671838
Warning

Warning

There is not support for URL reference inside

671838
<tt>`centos-art.sh'</tt> script.  The <tt>`centos-art.sh'</tt> script is
671838
designed to work with local files inside the working copy only.
671838

aaf678
671838

As CentOS Artwork Repository is built over a version control system,

671838
file movements inside the repository are considered repository
671838
changes. In order for these repository changes to be versioned, we
671838
need to, firstly, add changes into the version control system, commit
671838
them, and later, perform movement actions using version control system
671838
commands. This configuration makes possible for everyone to know about
671838
changes details inside the repository; and if needed, revert or update
671838
them back to a previous revision.
671838

671838

Finally, once all path information has been corrected, it is time to

671838
take care of information inside the files. For instance, considere
671838
what would happen if you make a reference to a documentation node, and
671838
later the documentation node you refere to is deleted. That would make
671838
Texinfo to produce error messages at export time. So, the
671838
<tt>`centos-art.sh'</tt> script needs to know when such changes happen, in
671838
a way they could be noted and handled without producing errors.
671838

010b2d
063806
671838

2.57.2.6 What is the right place to store it?

671838
671838

Occasionly, you may find that new corporate visual identity components

671838
need to be added to the repository. If that is your case, the first
671838
question you need to ask yourself, before start to create directories
671838
blindly all over, is: What is the right place to store it?
671838

671838

The CentOS Community different free support vains (see:

671838
http://wiki.centos.org/GettingHelp) are the best place to find
671838
answers to your question, but going there with hands empty is not good
671838
idea. It may give the impression you don't really care about. Instead,
671838
consider the following suggestions to find your own comprehension and
671838
so, make your propositions based on it.
671838

671838

When we are looking for the correct place to store new files, to bear

671838
in mind the corporate visual identity structure used inside the CentOS
671838
Artwork Repository (see section The <tt>`trunk/Identity'</tt> Directory) would be probaly the best
671838
advice we could offer, the rest is just matter of choosing appropriate
671838
names.  To illustrate this desition process let's consider the
671838
<tt>`trunk/Identity/Themes/Motifs/TreeFlower'</tt> directory as example.
671838
It is the trunk development line of TreeFlower artistic motif.
671838
Artistic motifs are considered part of themes, which in turn are
671838
considered part of CentOS corporate visual identity.
671838

671838

When building parent directory structures, you may find that reaching

671838
an acceptable location may take some time, and as it uses to happen
671838
most of time; once you've find it, that may be not a definite
671838
solution.  There are many concepts that you need to play with, in
671838
order to find a result that match the conceptual idea you try to
671838
implement in the new directory location. To know which these concepts
671838
are, split the location in words and read its documentation entry from
671838
less specific to more specific.
671838

671838

For example, the <tt>`trunk/Identity/Themes/Motifs/TreeFlower'</tt>

671838
location evolved through several months of contant work and there is
671838
no certain it won't change in the future, even it fixes quite well the
671838
concept we are trying to implement.  The concepts used in
671838
<tt>`trunk/Identity/Themes/Distro/Motifs/TreeFlower'</tt> location are
671838
described in the following commands, respectively:
671838

671838
centos-art manual --read=turnk/
671838
centos-art manual --read=turnk/Identity/
671838
centos-art manual --read=turnk/Identity/Themes/
671838
centos-art manual --read=turnk/Identity/Themes/Motifs/
671838
centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/
671838
671838

Other location concepts can be found similary as we did above, just

671838
change the location we used above by the one you are trying to know
671838
concepts for.
671838

671838
671838
671838

2.57.3 Usage

671838
671838
671838
centos-art path --copy='SRC' --to='DST'
671838
671838

Copy <samp>`SRC'</samp> to <samp>`DST'</samp> and schedule <samp>`DST'</samp> for

671838
addition (with history).  In this command, <tt>`SRC'</tt> and <tt>`DST'</tt>
671838
are both working copy (WC) entries.
671838

671838
671838
centos-art path --delete='SRC'
671838
671838

Delete <samp>`DST'</samp>. In order for this command to work the file or

671838
directory you intend to delete should be under version control first.
671838
In this command, <tt>`SRC'</tt> is a working copy (WC) entry.  
671838

671838
671838
671838
671838
671838
671838

2.57.4 See also

ee1f37
671838
671838
2.50 The <tt>`trunk/Scripts/Bash'</tt> Directory  
671838
671838
ee1f37
ee1f37
ee1f37
671838
[ < ]
671838
[ > ]
ee1f37
   
671838
[ << ]
671838
[ Up ]
671838
[ >> ]
ee1f37
ee1f37

ee1f37
 <font size="-1">
406f69
  This document was generated on March, 1 2011 using texi2html 1.76.
ee1f37
 </font>
ee1f37
 
ee1f37
ee1f37

ee1f37
</body>
ee1f37
</html>