Blame Manuals/Repository/repository-html/repository_56.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
-->
acd47b
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>
166893
<title>CentOS Artwork Repository: 3.53 trunk/Scripts/Bash/Functions/Path</title>
4c79b5
166893
<meta name="description" content="CentOS Artwork Repository: 3.53 trunk/Scripts/Bash/Functions/Path">
166893
<meta name="keywords" content="CentOS Artwork Repository: 3.53 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
4c79b5
2dc146
[ < ]
2dc146
[ > ]
4c79b5
   
300762
[ << ]
300762
[ Up ]
166893
[ >> ]
4c79b5
   
4c79b5
   
4c79b5
   
4c79b5
   
4c79b5
[Top]
4c79b5
[Contents]
166893
[Index]
4c79b5
[ ? ]
4c79b5
166893
2dc146
166893

3.53 trunk/Scripts/Bash/Functions/Path

2dc146
2dc146
2dc146
2dc146

3.53.1 Goals

2dc146
166893

This section exists to organize files related to path

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

2dc146
2dc146
2dc146

3.53.2 Description

2dc146
166893

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

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

4a9d2a
fa7cae
166893

3.53.2.1 Repository layout

166893
166893

The repository layout describes organization of files and directories

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

166893

As convenction, inside CentOS Artwork Repository, we organize files

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

166893

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

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

166893

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

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

166893

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

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

166893

The CentOS Artwork Repository layout is firmly grounded on a

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

166893
166893
166893

3.53.2.2 Repository name convenctions

166893
166893

Repository name convenctions help us to maintain consistency of names

166893
inside the repository.
166893

166893

Repository name convenctions are applied to files and directories

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

166893

Repository name convenctions are implemented inside the

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

166893
166893
166893

3.53.2.3 Repository work flow

166893
166893

Repository work flow describes the steps and time intervals used to

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

166893

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

166893
cycle. 
166893

166893

Initially, we start working themes on their trunk development line

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

166893

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

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

166893

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

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

166893

Both branches and tags, inside CentOS Artwork Repository, use

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

166893
Convenction

Convenction

Do not freeze trunk development lines using tags

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

166893
166893

The trunk development line may introduce problems we cannot see

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

166893

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

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

166893

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

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

166893

Before releasing a new major release of CentOS distribution we create

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

166893
166893
166893

3.53.2.4 Parallel directories

166893
166893

Inside CentOS Artwork Repository, parallel directories are simple

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

166893

Parallel directories take their structure from one unique parent

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

166893

In some circumstances, parallel directories may be created removing

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

166893

Another example of parallel directory is the documentation structure

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

166893

Othertimes, parallel directories may add uncommon information to their

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

166893

When one parent directory changes, all their related parallel

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

166893
166893
166893

3.53.2.5 Syncronizing path information

166893
166893

Parallel directories are very useful to keep repository organized but

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

166893

In such cases, functionalities like manual may confuse

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

166893

In the specific case of documentation (the manual

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

166893

There is no immediate way for manual, and similar

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

166893
Warning

Warning

There is not support for URL reference inside

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

166893
166893

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

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

166893

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

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

166893
166893
166893

3.53.2.6 What is the right place to store it?

166893
166893

Occasionly, you may find that new corporate visual identity components

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

166893

The CentOS Community different free support vains (see:

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

166893

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

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

166893

When building parent directory structures, you may find that reaching

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

166893

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

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

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

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

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

166893
166893
2dc146

3.53.3 Usage

4a9d2a
166893
166893
centos-art path --copy='SRC' --to='DST'
166893
166893

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

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

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

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

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

166893
166893
4a9d2a
2dc146
166893
2dc146

3.53.4 See also

300762
166893
166893
3.48 trunk/Scripts/Bash  
166893
166893
3.49 trunk/Scripts/Bash/Functions  
166893
166893
4c79b5
4c79b5
4c79b5
166893
[ < ]
166893
[ > ]
4c79b5
   
300762
[ << ]
2dc146
[ Up ]
166893
[ >> ]
4c79b5
4c79b5

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

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