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

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

ee1f37
ee1f37
063806
063806

2.57.1 Goals

ee1f37
063806

This section exists to organize files related to path

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

ee1f37
063806
063806

2.57.2 Description

b9dbd3
063806

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

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

b9dbd3
063806
063806

2.57.2.1 Repository layout

b9dbd3
063806

The repository layout describes organization of files and directories

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

063806

As convenction, inside CentOS Artwork Repository, we organize files

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

063806

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

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

063806

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

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

063806

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

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

063806

The CentOS Artwork Repository layout is firmly grounded on a

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

b9dbd3
063806
063806

2.57.2.2 Repository name convenctions

b9dbd3
063806

Repository name convenctions help us to maintain consistency of names

063806
inside the repository.
063806

063806

Repository name convenctions are applied to files and directories

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

063806

Repository name convenctions are implemented inside the

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

b9dbd3
063806
063806

2.57.2.3 Repository work flow

b9dbd3
063806

Repository work flow describes the steps and time intervals used to

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

063806

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

063806
cycle. 
063806

063806

Initially, we start working themes on their trunk development line

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

063806

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

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

063806

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

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

063806

Both branches and tags, inside CentOS Artwork Repository, use

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

063806
Convenction

Convenction

Do not freeze trunk development lines using tags

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

b9dbd3
063806

The trunk development line may introduce problems we cannot see

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

063806

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

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

063806

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

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

063806

Before releasing a new major release of CentOS distribution we create

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

b9dbd3
063806
063806

2.57.2.4 Parallel directories

b9dbd3
063806

Inside CentOS Artwork Repository, parallel directories are simple

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

063806

Parallel directories take their structure from one unique parent

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

063806

In some circumstances, parallel directories may be created removing

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

063806

Another example of parallel directory is the documentation structure

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

063806

Othertimes, parallel directories may add uncommon information to their

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

063806

When one parent directory changes, all their related parallel

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

b130a0
063806
063806

2.57.2.5 Syncronizing path information

b9dbd3
063806

Parallel directories are very useful to keep repository organized but

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

063806

In such cases, functionalities like manual may confuse

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

063806

In the specific case of documentation (the manual

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

063806

There is no immediate way for manual, and similar

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

063806
Warning

Warning

There is not support for URL reference inside

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

aaf678
063806

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

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

063806

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

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

010b2d
063806
063806

2.57.2.6 What is the right place to store it?

ee1f37
063806

Occasionly, you may find that new corporate visual identity components

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

063806

The CentOS Community different free support vains (see:

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

063806

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

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

063806

When building parent directory structures, you may find that reaching

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

063806

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

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

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

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

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

063806
063806
063806

2.57.3 Usage

063806
063806
063806
centos-art path --copy='SRC' --to='DST'
b9dbd3
063806

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

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

b9dbd3
063806
centos-art path --delete='SRC'
b9dbd3
063806

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

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

b9dbd3
b9dbd3
b9dbd3
ee1f37
063806
063806

2.57.4 See also

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