Blame Manuals/Filesystem/filesystem-html/filesystem_55.html

ee1f37
ee1f37
<html>
ee1f37
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
-->
ee1f37
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>
db14a4
<title>CentOS Artwork Repository: 3.52 trunk/Scripts/Bash/Functions/Path</title>
ee1f37
db14a4
<meta name="description" content="CentOS Artwork Repository: 3.52 trunk/Scripts/Bash/Functions/Path">
db14a4
<meta name="keywords" content="CentOS Artwork Repository: 3.52 trunk/Scripts/Bash/Functions/Path">
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
db14a4
[ < ]
ee1f37
[ > ]
ee1f37
   
db14a4
[ << ]
db14a4
[ Up ]
db14a4
[ >> ]
ee1f37
   
ee1f37
   
ee1f37
   
ee1f37
   
db14a4
[Top]
db14a4
[Contents]
db14a4
[Index]
db14a4
[ ? ]
ee1f37
ee1f37
ee1f37
ee1f37

3.52 trunk/Scripts/Bash/Functions/Path

ee1f37
ee1f37
ee1f37
ee1f37

3.52.1 Goals

ee1f37
ee1f37

This section exists to organize files related to path

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

ee1f37
ee1f37
ee1f37

3.52.2 Description

ee1f37
ee1f37

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

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

ee1f37
ee1f37
ee1f37

3.52.2.1 Repository layout

ee1f37
ee1f37

The repository layout describes organization of files and directories

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

ee1f37

As convenction, inside CentOS Artwork Repository, we organize files

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

db14a4

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

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

db14a4

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

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

db14a4

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

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

ee1f37

The CentOS Artwork Repository layout is firmly grounded on a

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

ee1f37
ee1f37
ee1f37

3.52.2.2 Repository name convenctions

ee1f37
ee1f37

Repository name convenctions help us to maintain consistency of names

ee1f37
inside the repository.
ee1f37

ee1f37

Repository name convenctions are applied to files and directories

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

ee1f37

Repository name convenctions are implemented inside the

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

ee1f37
ee1f37
ee1f37

3.52.2.3 Repository work flow

ee1f37
ee1f37

Repository work flow describes the steps and time intervals used to

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

ee1f37

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

ee1f37
cycle. 
ee1f37

ee1f37

Initially, we start working themes on their trunk development line

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

ee1f37

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

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

ee1f37

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

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

ee1f37

Both branches and tags, inside CentOS Artwork Repository, use

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

ee1f37
Convenction

Convenction

Do not freeze trunk development lines using tags

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

ee1f37
ee1f37

The trunk development line may introduce problems we cannot see

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

ee1f37

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

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

ee1f37

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

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

ee1f37

Before releasing a new major release of CentOS distribution we create

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

ee1f37
ee1f37
ee1f37

3.52.2.4 Parallel directories

ee1f37
ee1f37

Inside CentOS Artwork Repository, parallel directories are simple

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

ee1f37

Parallel directories take their structure from one unique parent

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

ee1f37

In some circumstances, parallel directories may be created removing

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

ee1f37

Another example of parallel directory is the documentation structure

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

ee1f37

Othertimes, parallel directories may add uncommon information to their

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

ee1f37

When one parent directory changes, all their related parallel

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

ee1f37
ee1f37
ee1f37

3.52.2.5 Syncronizing path information

ee1f37
ee1f37

Parallel directories are very useful to keep repository organized but

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

ee1f37

In such cases, functionalities like manual may confuse

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

ee1f37

In the specific case of documentation (the manual

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

ee1f37

There is no immediate way for manual, and similar

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

ee1f37
Warning

Warning

There is not support for URL reference inside

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

ee1f37
ee1f37

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

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

ee1f37

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

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

ee1f37
ee1f37
ee1f37

3.52.2.6 What is the right place to store it?

ee1f37
ee1f37

Occasionly, you may find that new corporate visual identity components

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

ee1f37

The CentOS Community different free support vains (see:

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

ee1f37

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

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

ee1f37

When building parent directory structures, you may find that reaching

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

ee1f37

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

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

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

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

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

ee1f37
ee1f37
ee1f37

3.52.3 Usage

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

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

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

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

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

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

ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37

3.52.4 See also

ee1f37
ee1f37
db14a4
3.47 trunk/Scripts/Bash  
ee1f37
db14a4
3.48 trunk/Scripts/Bash/Functions  
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
[ < ]
db14a4
[ > ]
ee1f37
   
db14a4
[ << ]
ee1f37
[ Up ]
db14a4
[ >> ]
ee1f37
ee1f37

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

ee1f37
</body>
ee1f37
</html>