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

3.52 trunk/Scripts/Bash/Functions/Path

b0644c
b0644c
d11e55
e37211

3.52.1 Goals

b0644c
2c3589

This section exists to organize files related to path

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

035049
d11e55
e37211

3.52.2 Description

b0644c
2c3589

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

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

4a9d2a
d11e55
2c3589

3.52.2.1 Repository layout

2c3589
2c3589

The repository layout describes organization of files and directories

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

2c3589

As convenction, inside CentOS Artwork Repository, we organize files

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

2c3589

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

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

2c3589

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

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

2c3589

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

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

2c3589

The CentOS Artwork Repository layout is firmly grounded on a

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

2c3589
2c3589
2c3589

3.52.2.2 Repository name convenctions

2c3589
2c3589

Repository name convenctions help us to maintain consistency of names

2c3589
inside the repository.
2c3589

2c3589

Repository name convenctions are applied to files and directories

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

2c3589

Repository name convenctions are implemented inside the

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

2c3589
2c3589
2c3589

3.52.2.3 Repository work flow

2c3589
2c3589

Repository work flow describes the steps and time intervals used to

2c3589
produce CentOS corporate visual identity inside CentOS Artwork
2c3589
Repository.  
2c3589

2c3589

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

2c3589
cycle. 
2c3589

2c3589

Initially, we start working themes on their trunk development line

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

2c3589

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

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

2c3589

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

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

2c3589

Both branches and tags, inside CentOS Artwork Repository, use

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

2c3589
Convenction

Convenction

Do not freeze trunk development lines using tags

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

2c3589
2c3589

The trunk development line may introduce problems we cannot see

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

2c3589

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

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

2c3589

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

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

2c3589

Before releasing a new major release of CentOS distribution we create

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

2c3589
2c3589
2c3589

3.52.2.4 Parallel directories

2c3589
2c3589

Inside CentOS Artwork Repository, parallel directories are simple

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

2c3589

Parallel directories take their structure from one unique parent

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

2c3589

In some circumstances, parallel directories may be created removing

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

2c3589

Another example of parallel directory is the documentation structure

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

2c3589

Othertimes, parallel directories may add uncommon information to their

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

2c3589

When one parent directory changes, all their related parallel

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

2c3589
2c3589
2c3589

3.52.2.5 Syncronizing path information

2c3589
2c3589

Parallel directories are very useful to keep repository organized but

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

2c3589

In such cases, functionalities like manual may confuse

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

2c3589

In the specific case of documentation (the manual

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

2c3589

There is no immediate way for manual, and similar

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

2c3589
Warning

Warning

There is not support for URL reference inside

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

2c3589
2c3589

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

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

2c3589

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

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

2c3589
2c3589
2c3589

3.52.2.6 What is the right place to store it?

2c3589
2c3589

Occasionly, you may find that new corporate visual identity components

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

2c3589

The CentOS Community different free support vains (see:

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

2c3589

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

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

2c3589

When building parent directory structures, you may find that reaching

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

2c3589

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

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

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

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

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

2c3589
2c3589
4a9d2a

3.52.3 Usage

4a9d2a
d11e55
2c3589
centos-art path --copy='SRC' --to='DST'
2c3589
2c3589

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

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

2c3589
2c3589
centos-art path --delete='SRC'
2c3589
2c3589

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

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

2c3589
d11e55
4a9d2a
ec5f63
2c3589
008ee0

3.52.4 See also

bc3531
2c3589
2c3589
3.47 trunk/Scripts/Bash  
2c3589
2c3589
3.48 trunk/Scripts/Bash/Functions  
2c3589
2c3589
4c79b5
2c8180
4c79b5
2c3589
[ < ]
2c3589
[ > ]
4c79b5
   
4c79b5
[ << ]
d11e55
[ Up ]
2c3589
[ >> ]
4c79b5
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>