Blame Manual/repository-html/repository_59.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
-->
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>
b9dbd3
<title>CentOS Artwork Repository: 2.57 The trunk/Scripts/Bash/Cli/Functions/Path Directory</title>
ee1f37
b9dbd3
<meta name="description" content="CentOS Artwork Repository: 2.57 The trunk/Scripts/Bash/Cli/Functions/Path Directory">
b9dbd3
<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
b9dbd3
[ < ]
b9dbd3
[ > ]
ee1f37
   
b9dbd3
[ << ]
b9dbd3
[ Up ]
b9dbd3
[ >> ]
ee1f37
   
ee1f37
   
ee1f37
   
ee1f37
   
56a476
[Top]
56a476
[Contents]
b130a0
[Index]
56a476
[ ? ]
ee1f37
b9dbd3
b9dbd3
b9dbd3

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

b9dbd3
b9dbd3
b9dbd3
b9dbd3

2.57.1 Goals

b9dbd3
b9dbd3

This section exists to organize files related to path

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

b9dbd3
b9dbd3
b9dbd3

2.57.2 Description

b9dbd3
b9dbd3

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

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

b9dbd3
b9dbd3
b9dbd3

2.57.2.1 Repository layout

b9dbd3
b9dbd3

The repository layout describes organization of files and directories

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

b9dbd3

As convenction, inside CentOS Artwork Repository, we organize files

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

b9dbd3

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

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

b9dbd3

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

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

b9dbd3

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

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

b9dbd3

The CentOS Artwork Repository layout is firmly grounded on a

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

b9dbd3
b9dbd3
b9dbd3

2.57.2.2 Repository name convenctions

b9dbd3
b9dbd3

Repository name convenctions help us to maintain consistency of names

b9dbd3
inside the repository.
b9dbd3

b9dbd3

Repository name convenctions are applied to files and directories

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

b9dbd3

Repository name convenctions are implemented inside the

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

b9dbd3
b9dbd3
b9dbd3

2.57.2.3 Repository work flow

b9dbd3
b9dbd3

Repository work flow describes the steps and time intervals used to

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

b9dbd3

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

b9dbd3
cycle. 
b9dbd3

b9dbd3

Initially, we start working themes on their trunk development line

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

b9dbd3

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

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

b9dbd3

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

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

b9dbd3

Both branches and tags, inside CentOS Artwork Repository, use

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

b9dbd3
Convenction

Convenction

Do not freeze trunk development lines using tags

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

aaf678
b9dbd3

The trunk development line may introduce problems we cannot see

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

b9dbd3

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

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

b9dbd3

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

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

b9dbd3

Before releasing a new major release of CentOS distribution we create

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

b9dbd3
b9dbd3
b9dbd3

2.57.2.4 Parallel directories

b9dbd3
b9dbd3

Inside CentOS Artwork Repository, parallel directories are simple

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

b9dbd3

Parallel directories take their structure from one unique parent

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

b9dbd3

In some circumstances, parallel directories may be created removing

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

b9dbd3

Another example of parallel directory is the documentation structure

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

b9dbd3

Othertimes, parallel directories may add uncommon information to their

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

b9dbd3

When one parent directory changes, all their related parallel

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

b9dbd3
b9dbd3
b9dbd3

2.57.2.5 Syncronizing path information

b9dbd3
b9dbd3

Parallel directories are very useful to keep repository organized but

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

b9dbd3

In such cases, functionalities like manual may confuse

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

b9dbd3

In the specific case of documentation (the manual

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

b9dbd3

There is no immediate way for manual, and similar

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

b9dbd3
Warning

Warning

There is not support for URL reference inside

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

aaf678
b9dbd3

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

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

b9dbd3

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

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

b9dbd3
b9dbd3
b9dbd3

2.57.2.6 What is the right place to store it?

b9dbd3
b9dbd3

Occasionly, you may find that new corporate visual identity components

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

b9dbd3

The CentOS Community different free support vains (see:

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

b9dbd3

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

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

b9dbd3

When building parent directory structures, you may find that reaching

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

b9dbd3

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

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

b9dbd3
centos-art manual --read=turnk/
b9dbd3
centos-art manual --read=turnk/Identity/
b9dbd3
centos-art manual --read=turnk/Identity/Themes/
b9dbd3
centos-art manual --read=turnk/Identity/Themes/Motifs/
b9dbd3
centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/
010b2d
b9dbd3

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

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

b130a0
b9dbd3
b9dbd3

2.57.3 Usage

b130a0
010b2d
b9dbd3
centos-art path --copy='SRC' --to='DST'
010b2d
b9dbd3

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

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

ee1f37
b9dbd3
centos-art path --delete='SRC'
010b2d
b9dbd3

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

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

b9dbd3
ee1f37
ee1f37
982d5c
b9dbd3
b9dbd3

2.57.4 See also

b130a0
b9dbd3
b9dbd3
2.50 The <tt>`trunk/Scripts/Bash'</tt> Directory  
b9dbd3
b9dbd3
ee1f37
ee1f37
ee1f37
b9dbd3
[ < ]
b9dbd3
[ > ]
ee1f37
   
b9dbd3
[ << ]
b9dbd3
[ Up ]
b9dbd3
[ >> ]
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>