Blame Manual/repository-html/repository_72.html

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

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

632e8b
632e8b
995423
9bfd15

2.68.1 Goals

9bfd15
9bfd15

This section exists to organize files related to path

9bfd15
functiontionality.  The path functionality standardizes
9bfd15
movement, syncronization, branching, tagging, and general file
9bfd15
maintainance inside the repository. 
632e8b

632e8b
995423
9bfd15

2.68.2 Description

632e8b
9bfd15

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

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

632e8b
995423
9bfd15

2.68.2.1 Repository layout

9bfd15
9bfd15

The repository layout describes organization of files and directories

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

9bfd15

As convenction, inside CentOS Artwork Repository, we organize files

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

995423

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

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

9bfd15

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

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

995423

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

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

9bfd15

The CentOS Artwork Repository layout is firmly grounded on a

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

9bfd15
995423
9bfd15

2.68.2.2 Repository name convenctions

9bfd15
9bfd15

Repository name convenctions help us to maintain consistency of names

9bfd15
inside the repository.
632e8b

9bfd15

Repository name convenctions are applied to files and directories

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

9bfd15

Repository name convenctions are implemented inside the

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

632e8b
995423
9bfd15

2.68.2.3 Repository work flow

9bfd15
9bfd15

Repository work flow describes the steps and time intervals used to

9bfd15
produce CentOS corporate visual identity inside CentOS Artwork
9bfd15
Repository.  
9bfd15

9bfd15

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

9bfd15
cycle. 
9bfd15

9bfd15

Initially, we start working themes on their trunk development line

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

9bfd15

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

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

9bfd15

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

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

9bfd15

Both branches and tags, inside CentOS Artwork Repository, use

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

9bfd15
Convenction

Convenction

Do not freeze trunk development lines using tags

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

632e8b
9bfd15

The trunk development line may introduce problems we cannot see

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

9bfd15

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

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

9bfd15

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

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

9bfd15

Before releasing a new major release of CentOS distribution we create

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

632e8b
995423
9bfd15

2.68.2.4 Parallel directories

9bfd15
9bfd15

Inside CentOS Artwork Repository, parallel directories are simple

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

9bfd15

Parallel directories take their structure from one unique parent

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

9bfd15

In some circumstances, parallel directories may be created removing

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

9bfd15

Another example of parallel directory is the documentation structure

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

9bfd15

Othertimes, parallel directories may add uncommon information to their

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

9bfd15

When one parent directory changes, all their related parallel

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

632e8b
995423
9bfd15

2.68.2.5 Syncronizing path information

9bfd15
9bfd15

Parallel directories are very useful to keep repository organized but

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

9bfd15

In such cases, functionalities like manual may confuse

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

9bfd15

In the specific case of documentation (the manual

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

9bfd15

There is no immediate way for manual, and similar

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

9bfd15
Warning

Warning

There is not support for URL reference inside

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

632e8b
9bfd15

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

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

9bfd15

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

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

632e8b
995423
9bfd15

2.68.2.6 What is the right place to store it?

9bfd15
9bfd15

Occasionly, you may find that new corporate visual identity components

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

9bfd15

The CentOS Community different free support vains (see:

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

9bfd15

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

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

9bfd15

When building parent directory structures, you may find that reaching

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

9bfd15

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

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

9bfd15
centos-art manual --read=turnk/
9bfd15
centos-art manual --read=turnk/Identity/
9bfd15
centos-art manual --read=turnk/Identity/Themes/
9bfd15
centos-art manual --read=turnk/Identity/Themes/Motifs/
9bfd15
centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/
632e8b
9bfd15

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

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

632e8b
995423
9bfd15

2.68.3 Usage

632e8b
632e8b
9bfd15
centos-art path --copy='SRC' --to='DST'
632e8b
9bfd15

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

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

632e8b
9bfd15
centos-art path --delete='SRC'
632e8b
9bfd15

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

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

9bfd15
632e8b
632e8b
632e8b
995423
9bfd15

2.68.4 See also

632e8b
9bfd15
995423
2.61 The <tt>`trunk/Scripts/Bash'</tt> Directory  
9bfd15
9bfd15
632e8b
632e8b
632e8b
995423
[ < ]
995423
[ > ]
632e8b
   
632e8b
[ << ]
995423
[ Up ]
995423
[ >> ]
632e8b
632e8b

632e8b
 <font size="-1">
995423
  This document was generated on March, 9 2011 using texi2html 1.76.
632e8b
 </font>
632e8b
 
632e8b
632e8b

632e8b
</body>
632e8b
</html>