Blame Manual/repository-html/repository_57.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>
861ed3
<title>CentOS Artwork Repository: 1.56 The trunk/Scripts/Bash/Cli/Functions/Path Directory</title>
ee1f37
861ed3
<meta name="description" content="CentOS Artwork Repository: 1.56 The trunk/Scripts/Bash/Cli/Functions/Path Directory">
861ed3
<meta name="keywords" content="CentOS Artwork Repository: 1.56 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
aaf678
[ < ]
aaf678
[ > ]
ee1f37
   
aaf678
[ << ]
aaf678
[ Up ]
aaf678
[ >> ]
ee1f37
   
ee1f37
   
ee1f37
   
ee1f37
   
56a476
[Top]
56a476
[Contents]
5cb5a7
[Index]
56a476
[ ? ]
ee1f37
aaf678
aaf678
861ed3

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

ee1f37
ee1f37
aaf678
aaf678

1.56.1 Goals

ee1f37
aaf678

This section exists to organize files related to path

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

ee1f37
aaf678
aaf678

1.56.2 Description

ee1f37
aaf678

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

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

ee1f37
aaf678
aaf678

1.56.2.1 Repository layout

ee1f37
aaf678

The repository layout describes organization of files and directories

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

aaf678

As convenction, inside CentOS Artwork Repository, we organize files

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

861ed3

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

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

aaf678

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

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

861ed3

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

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

aaf678

The CentOS Artwork Repository layout is firmly grounded on a

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

010b2d
aaf678
aaf678

1.56.2.2 Repository name convenctions

010b2d
aaf678

Repository name convenctions help us to maintain consistency of names

aaf678
inside the repository.
aaf678

aaf678

Repository name convenctions are applied to files and directories

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

aaf678

Repository name convenctions are implemented inside the

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

ee1f37
aaf678
aaf678

1.56.2.3 Repository work flow

ee1f37
aaf678

Repository work flow describes the steps and time intervals used to

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

aaf678

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

aaf678
cycle. 
aaf678

aaf678

Initially, we start working themes on their trunk development line

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

aaf678

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

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

aaf678

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

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

aaf678

Both branches and tags, inside CentOS Artwork Repository, use

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

aaf678
Convenction

Convenction

Do not freeze trunk development lines using tags

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

aaf678
aaf678

The trunk development line may introduce problems we cannot see

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

aaf678

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

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

aaf678

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

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

aaf678

Before releasing a new major release of CentOS distribution we create

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

aaf678
aaf678
aaf678

1.56.2.4 Parallel directories

aaf678
aaf678

Inside CentOS Artwork Repository, parallel directories are simple

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

aaf678

Parallel directories take their structure from one unique parent

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

aaf678

In some circumstances, parallel directories may be created removing

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

aaf678

Another example of parallel directory is the documentation structure

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

aaf678

Othertimes, parallel directories may add uncommon information to their

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

aaf678

When one parent directory changes, all their related parallel

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

aaf678
aaf678
aaf678

1.56.2.5 Syncronizing path information

aaf678
aaf678

Parallel directories are very useful to keep repository organized but

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

aaf678

In such cases, functionalities like manual may confuse

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

aaf678

In the specific case of documentation (the manual

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

aaf678

There is no immediate way for manual, and similar

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

aaf678
Warning

Warning

There is not support for URL reference inside

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

aaf678
aaf678

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

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

aaf678

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

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

aaf678
aaf678
aaf678

1.56.2.6 What is the right place to store it?

aaf678
aaf678

Occasionly, you may find that new corporate visual identity components

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

aaf678

The CentOS Community different free support vains (see:

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

aaf678

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

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

aaf678

When building parent directory structures, you may find that reaching

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

aaf678

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

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

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

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

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

aaf678
aaf678
aaf678

1.56.3 Usage

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

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

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

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

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

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

aaf678
aaf678
aaf678
aaf678
aaf678
aaf678

1.56.4 See also

ee1f37
aaf678
861ed3
1.49 The <tt>`trunk/Scripts/Bash'</tt> Directory  
aaf678
aaf678
ee1f37
ee1f37
ee1f37
aaf678
[ < ]
aaf678
[ > ]
ee1f37
   
aaf678
[ << ]
aaf678
[ Up ]
aaf678
[ >> ]
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>