Blame Manuals/Repository/en/Html/repository_44.html

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

3.41 trunk/Scripts/Bash/Functions/Path

b0644c
b0644c
5cee2c
e37211

3.41.1 Goals

e37211
ec5f63

This section exists to organize files related to path

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

63f275
5cee2c
e37211

3.41.2 Description

e37211
ec5f63

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

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

1d1bf4
5cee2c
ec5f63

3.41.2.1 Repository layout

1d1bf4
ec5f63

The repository layout describes organization of files and directories

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

ec5f63

As convenction, inside CentOS Artwork Repository, we organize files

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

ec5f63
ec5f63

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-6

1d1bf4
ec5f63

Figure 3.15: The CentOS Artwork Repository layout.

ec5f63
ec5f63

ec5f63

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

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

ec5f63

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

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

ec5f63

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

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

ec5f63

The CentOS Artwork Repository layout is firmly grounded on a

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

1d1bf4
5cee2c
ec5f63

3.41.2.2 Repository name convenctions

ec5f63
ec5f63

Repository name convenctions help us to maintain consistency of names

ec5f63
inside the repository.
ec5f63

ec5f63

Repository name convenctions are applied to files and directories

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

ec5f63

Repository name convenctions are implemented inside the

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

ec5f63
5cee2c
ec5f63

3.41.2.3 Repository work flow

ec5f63
ec5f63

Repository work flow describes the steps and time intervals used to

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

ec5f63

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

ec5f63
cycle. 
ec5f63

ec5f63

Initially, we start working themes on their trunk development line

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

ec5f63

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

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

ec5f63

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

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

ec5f63

Both branches and tags, inside CentOS Artwork Repository, use

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

ec5f63
ec5f63

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-1

ec5f63
ec5f63

Figure 3.16: Name convention for tags and branches creation.

ec5f63
ec5f63

ec5f63
Convenction

Convenction

Do not freeze trunk development lines using tags

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

ec5f63
ec5f63

The trunk development line may introduce problems we cannot see

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

ec5f63

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

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

ec5f63

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

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

ec5f63

Before releasing a new major release of CentOS distribution we create

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

ec5f63
5cee2c
ec5f63

3.41.2.4 Parallel directories

ec5f63
ec5f63

Inside CentOS Artwork Repository, parallel directories are simple

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

ec5f63

Parallel directories take their structure from one unique parent

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

ec5f63

In some circumstances, parallel directories may be created removing

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

ec5f63
ec5f63

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-3

ec5f63
ec5f63

Figure 3.17: Parallel directories removing uncommon information.

ec5f63
ec5f63

ec5f63

Another example of parallel directory is the documentation structure

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

ec5f63

Othertimes, parallel directories may add uncommon information to their

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

ec5f63
ec5f63

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-4

ec5f63
ec5f63

Figure 3.18: Parallel directories adding uncommon information.

ec5f63
ec5f63

ec5f63

When one parent directory changes, all their related parallel

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

ec5f63
ec5f63

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-5

ec5f63
ec5f63

Figure 3.19: Wrong construction of parallel directories.

ec5f63
ec5f63

ec5f63
5cee2c
ec5f63

3.41.2.5 Syncronizing path information

ec5f63
ec5f63

Parallel directories are very useful to keep repository organized but

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

ec5f63

In such cases, functionalities like manual may confuse

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

ec5f63

In the specific case of documentation (the manual

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

ec5f63

There is no immediate way for manual, and similar

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

ec5f63
Warning

Warning

There is not support for URL reference inside

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

ec5f63
ec5f63

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

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

ec5f63

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

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

ec5f63
5cee2c
ec5f63

3.41.2.6 What is the right place to store it?

ec5f63
ec5f63

Occasionly, you may find that new corporate visual identity components

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

ec5f63

The CentOS Community different free support vains (see:

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

ec5f63

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

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

ec5f63

When building parent directory structures, you may find that reaching

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

ec5f63

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

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

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

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

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

ec5f63
5cee2c
ec5f63

3.41.3 Usage

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

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

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

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

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

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

ec5f63
ec5f63
ec5f63
ec5f63
5cee2c
54264c

3.41.4 See also

4c79b5
ec5f63
5cee2c
3.36 trunk/Scripts/Bash  
ec5f63
5cee2c
3.37 trunk/Scripts/Bash/Functions  
ec5f63
ec5f63
4c79b5
4c79b5
4c79b5
5cee2c
[ < ]
5cee2c
[ > ]
4c79b5
   
4c79b5
[ << ]
5cee2c
[ Up ]
13b177
[ >> ]
4c79b5
4c79b5

4c79b5
 <font size="-1">
139290
  This document was generated on January, 14 2011 using texi2html 1.76.
4c79b5
 </font>
4c79b5
 
4c79b5
4c79b5

4c79b5
</body>
4c79b5
</html>