Blame Manuals/Repository/repository-html/repository_57.html

4c79b5
4c79b5
<html>
ccb7a3
4c79b5
4c79b5
Permission is granted to copy, distribute and/or modify this document
4c79b5
under the terms of the GNU Free Documentation License, Version 1.2 or
4c79b5
any later version published by the Free Software Foundation; with no
4c79b5
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
4c79b5
copy of the license is included in the section entitled GNU Free
4c79b5
Documentation License.  
4c79b5
-->
bf28e1
4c79b5
4c79b5
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
4c79b5
            Karl Berry  <karl@freefriends.org>
4c79b5
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
4c79b5
            and many others.
4c79b5
Maintained by: Many creative people <dev@texi2html.cvshome.org>
4c79b5
Send bugs and suggestions to <users@texi2html.cvshome.org>
4c79b5
4c79b5
-->
4c79b5
<head>
70ef27
<title>CentOS Artwork Repository: 3.54 trunk/Scripts/Bash/Functions/Path</title>
4c79b5
70ef27
<meta name="description" content="CentOS Artwork Repository: 3.54 trunk/Scripts/Bash/Functions/Path">
70ef27
<meta name="keywords" content="CentOS Artwork Repository: 3.54 trunk/Scripts/Bash/Functions/Path">
4c79b5
<meta name="resource-type" content="document">
4c79b5
<meta name="distribution" content="global">
4c79b5
<meta name="Generator" content="texi2html 1.76">
4c79b5
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
4c79b5
<style type="text/css">
4c79b5
1e9202
@import "/home/centos/artwork/trunk/Identity/Models/Css/Texi2html/common.css";
4c79b5
4c79b5
a.summary-letter {text-decoration: none}
4c79b5
pre.display {font-family: serif}
4c79b5
pre.format {font-family: serif}
4c79b5
pre.menu-comment {font-family: serif}
4c79b5
pre.menu-preformatted {font-family: serif}
4c79b5
pre.smalldisplay {font-family: serif; font-size: smaller}
4c79b5
pre.smallexample {font-size: smaller}
4c79b5
pre.smallformat {font-family: serif; font-size: smaller}
4c79b5
pre.smalllisp {font-size: smaller}
4c79b5
span.sansserif {font-family:sans-serif; font-weight:normal;}
4c79b5
ul.toc {list-style: none}
4c79b5
-->
4c79b5
</style>
4c79b5
4c79b5
4c79b5
</head>
4c79b5
4c79b5
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
4c79b5
300762
70ef27
[ < ]
70ef27
[ > ]
4c79b5
   
4c79b5
[ << ]
4c79b5
[ Up ]
70ef27
[ >> ]
4c79b5
   
4c79b5
   
4c79b5
   
4c79b5
   
4c79b5
[Top]
4c79b5
[Contents]
70ef27
[Index]
4c79b5
[ ? ]
4c79b5
70ef27
70ef27
70ef27

3.54 trunk/Scripts/Bash/Functions/Path

70ef27
70ef27
70ef27
70ef27

3.54.1 Goals

70ef27
70ef27

This section exists to organize files related to path

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

70ef27
70ef27
70ef27

3.54.2 Description

70ef27
70ef27

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

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

70ef27
70ef27
70ef27

3.54.2.1 Repository layout

70ef27
70ef27

The repository layout describes organization of files and directories

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

70ef27

As convenction, inside CentOS Artwork Repository, we organize files

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

70ef27

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

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

70ef27

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

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

70ef27

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

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

70ef27

The CentOS Artwork Repository layout is firmly grounded on a

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

70ef27
70ef27
70ef27

3.54.2.2 Repository name convenctions

70ef27
70ef27

Repository name convenctions help us to maintain consistency of names

70ef27
inside the repository.
70ef27

70ef27

Repository name convenctions are applied to files and directories

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

70ef27

Repository name convenctions are implemented inside the

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

70ef27
70ef27
70ef27

3.54.2.3 Repository work flow

70ef27
70ef27

Repository work flow describes the steps and time intervals used to

70ef27
produce CentOS corporate visual identity inside CentOS Artwork
70ef27
Repository.  
70ef27

70ef27

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

70ef27
cycle. 
70ef27

70ef27

Initially, we start working themes on their trunk development line

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

70ef27

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

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

70ef27

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

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

70ef27

Both branches and tags, inside CentOS Artwork Repository, use

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

70ef27
Convenction

Convenction

Do not freeze trunk development lines using tags

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

d11e55
70ef27

The trunk development line may introduce problems we cannot see

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

70ef27

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

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

70ef27

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

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

70ef27

Before releasing a new major release of CentOS distribution we create

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

c2a1bc
70ef27
70ef27

3.54.2.4 Parallel directories

70ef27
70ef27

Inside CentOS Artwork Repository, parallel directories are simple

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

70ef27

Parallel directories take their structure from one unique parent

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

70ef27

In some circumstances, parallel directories may be created removing

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

70ef27

Another example of parallel directory is the documentation structure

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

70ef27

Othertimes, parallel directories may add uncommon information to their

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

70ef27

When one parent directory changes, all their related parallel

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

7e35dc
70ef27
70ef27

3.54.2.5 Syncronizing path information

70ef27
70ef27

Parallel directories are very useful to keep repository organized but

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

70ef27

In such cases, functionalities like manual may confuse

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

70ef27

In the specific case of documentation (the manual

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

70ef27

There is no immediate way for manual, and similar

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

70ef27
Warning

Warning

There is not support for URL reference inside

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

c12cdc
70ef27

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

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

70ef27

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

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

2b5e61
70ef27
70ef27

3.54.2.6 What is the right place to store it?

70ef27
70ef27

Occasionly, you may find that new corporate visual identity components

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

70ef27

The CentOS Community different free support vains (see:

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

70ef27

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

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

70ef27

When building parent directory structures, you may find that reaching

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

70ef27

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

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

70ef27
centos-art manual --read=turnk/
70ef27
centos-art manual --read=turnk/Identity/
70ef27
centos-art manual --read=turnk/Identity/Themes/
70ef27
centos-art manual --read=turnk/Identity/Themes/Motifs/
70ef27
centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/
2c3589
70ef27

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

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

c2a1bc
70ef27
70ef27

3.54.3 Usage

bf28e1
7e35dc
70ef27
centos-art path --copy='SRC' --to='DST'
2c3589
70ef27

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

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

2c3589
70ef27
centos-art path --delete='SRC'
7e35dc
70ef27

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

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

70ef27
7e35dc
7e35dc
70ef27
70ef27
70ef27

3.54.4 See also

300762
ec5f63
70ef27
3.49 trunk/Scripts/Bash  
70ef27
70ef27
3.50 trunk/Scripts/Bash/Functions  
ec5f63
ec5f63
ec5f63
300762
300762
70ef27
[ < ]
70ef27
[ > ]
300762
   
300762
[ << ]
70ef27
[ Up ]
70ef27
[ >> ]
300762
4c79b5

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

4c79b5
</body>
4c79b5
</html>