Blame Manuals/Repository/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>
56a476
<title>CentOS Artwork Repository: 3.54 trunk/Scripts/Bash/Cli/Functions/Path</title>
ee1f37
56a476
<meta name="description" content="CentOS Artwork Repository: 3.54 trunk/Scripts/Bash/Cli/Functions/Path">
56a476
<meta name="keywords" content="CentOS Artwork Repository: 3.54 trunk/Scripts/Bash/Cli/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
56a476
[ < ]
010b2d
[ > ]
ee1f37
   
56a476
[ << ]
56a476
[ Up ]
56a476
[ >> ]
ee1f37
   
ee1f37
   
ee1f37
   
ee1f37
   
56a476
[Top]
56a476
[Contents]
56a476
[Index]
56a476
[ ? ]
ee1f37
406f69
010b2d
406f69

3.54 trunk/Scripts/Bash/Cli/Functions/Path

ee1f37
ee1f37
010b2d
ee1f37

3.54.1 Goals

ee1f37
010b2d

This section exists to organize files related to path

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

ee1f37
010b2d
ee1f37

3.54.2 Description

ee1f37
010b2d

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

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

ee1f37
010b2d
010b2d

3.54.2.1 Repository layout

ee1f37
010b2d

The repository layout describes organization of files and directories

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

010b2d

As convenction, inside CentOS Artwork Repository, we organize files

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

56a476

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

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

56a476

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

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

56a476

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

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

010b2d

The CentOS Artwork Repository layout is firmly grounded on a

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

ee1f37
010b2d
010b2d

3.54.2.2 Repository name convenctions

ee1f37
010b2d

Repository name convenctions help us to maintain consistency of names

010b2d
inside the repository.
010b2d

010b2d

Repository name convenctions are applied to files and directories

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

010b2d

Repository name convenctions are implemented inside the

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

ee1f37
010b2d
010b2d

3.54.2.3 Repository work flow

ee1f37
010b2d

Repository work flow describes the steps and time intervals used to

010b2d
produce CentOS corporate visual identity inside CentOS Artwork
010b2d
Repository.  
010b2d

010b2d

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

010b2d
cycle. 
010b2d

010b2d

Initially, we start working themes on their trunk development line

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

010b2d

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

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

010b2d

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

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

010b2d

Both branches and tags, inside CentOS Artwork Repository, use

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

010b2d
Convenction

Convenction

Do not freeze trunk development lines using tags

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

ee1f37
010b2d

The trunk development line may introduce problems we cannot see

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

010b2d

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

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

010b2d

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

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

010b2d

Before releasing a new major release of CentOS distribution we create

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

ee1f37
010b2d
010b2d

3.54.2.4 Parallel directories

ee1f37
010b2d

Inside CentOS Artwork Repository, parallel directories are simple

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

010b2d

Parallel directories take their structure from one unique parent

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

010b2d

In some circumstances, parallel directories may be created removing

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

010b2d

Another example of parallel directory is the documentation structure

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

010b2d

Othertimes, parallel directories may add uncommon information to their

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

010b2d

When one parent directory changes, all their related parallel

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

ee1f37
010b2d
010b2d

3.54.2.5 Syncronizing path information

ee1f37
010b2d

Parallel directories are very useful to keep repository organized but

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

010b2d

In such cases, functionalities like manual may confuse

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

010b2d

In the specific case of documentation (the manual

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

010b2d

There is no immediate way for manual, and similar

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

010b2d
Warning

Warning

There is not support for URL reference inside

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

ee1f37
010b2d

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

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

010b2d

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

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

ee1f37
010b2d
010b2d

3.54.2.6 What is the right place to store it?

ee1f37
010b2d

Occasionly, you may find that new corporate visual identity components

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

010b2d

The CentOS Community different free support vains (see:

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

010b2d

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

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

010b2d

When building parent directory structures, you may find that reaching

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

010b2d

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

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

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

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

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

010b2d
010b2d
010b2d

3.54.3 Usage

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

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

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

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

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

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

ee1f37
ee1f37
ee1f37
ee1f37
010b2d
ee1f37

3.54.4 See also

ee1f37
ee1f37
56a476
3.47 trunk/Scripts/Bash  
ee1f37
ee1f37
ee1f37
ee1f37
ee1f37
010b2d
[ < ]
56a476
[ > ]
ee1f37
   
56a476
[ << ]
010b2d
[ Up ]
56a476
[ >> ]
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>