Blame Identity/Manual/repository-xhtml/repository_74.xhtml

c8f7b7
728c6d
728c6d
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
728c6d
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
728c6d
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
728c6d
<head>
632e8b
c8f7b7
    <title>CentOS Artwork Repository: 2.67 The trunk/Scripts/Functions/Path Directory</title>
c8f7b7
c8f7b7
    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
728c6d
    <meta name="description" content="CentOS Artwork Repository: 2.67 The trunk/Scripts/Functions/Path Directory" />
728c6d
    <meta name="keywords" content="CentOS Artwork Repository: 2.67 The trunk/Scripts/Functions/Path Directory" />
728c6d
    <meta name="resource-type" content="document" />
728c6d
    <meta name="distribution" content="global" />
728c6d
    <meta name="generator" content="texi2html 1.76" />
728c6d
    <meta name="copyright" content="2009-2011 Alain Reguera Delgado" />
632e8b
c8f7b7
    <link href="/home/centos/artwork/trunk/Identity/Manual/repository.css" rel="stylesheet" type="text/css" media="screen projection" />
632e8b
728c6d
</head>
632e8b
728c6d
<body>
632e8b
728c6d
632e8b
728c6d
632e8b
728c6d
    
632e8b
728c6d
        
c8f7b7
c8f7b7
632e8b
c8f7b7
[ < ]
ed9de5
[ > ]
632e8b
   
c8f7b7
[ << ]
c8f7b7
[ Up ]
c8f7b7
[ >> ]
632e8b
   
632e8b
   
632e8b
   
632e8b
   
c8f7b7
[Top]
c8f7b7
[Contents]
c8f7b7
[Index]
c8f7b7
[ ? ]
632e8b
ed9de5
ed9de5
ed9de5

2.67 The <tt>`trunk/Scripts/Functions/Path'</tt> Directory

632e8b
728c6d

ed9de5
52772c

2.67.1 Goals

632e8b
ed9de5

This section exists to organize files related to path

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

728c6d

ed9de5
52772c

2.67.2 Description

9bfd15
ed9de5

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

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

728c6d

ed9de5
ed9de5

2.67.2.1 Repository layout

9bfd15
ed9de5

The repository layout describes organization of files and directories

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

ed9de5

As convenction, inside CentOS Artwork Repository, we organize files

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

c8f7b7

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

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

ed9de5

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

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

c8f7b7

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

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

ed9de5

The CentOS Artwork Repository layout is firmly grounded on a

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

728c6d

ed9de5
ed9de5

2.67.2.2 Repository name convenctions

ed9de5
ed9de5

Repository name convenctions help us to maintain consistency of names

ed9de5
inside the repository.
ed9de5

ed9de5

Repository name convenctions are applied to files and directories

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

ed9de5

Repository name convenctions are implemented inside the

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

728c6d

ed9de5
ed9de5

2.67.2.3 Repository work flow

ed9de5
ed9de5

Repository work flow describes the steps and time intervals used to

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

ed9de5

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

ed9de5
cycle. 
ed9de5

ed9de5

Initially, we start working themes on their trunk development line

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

ed9de5

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

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

ed9de5

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

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

ed9de5

Both branches and tags, inside CentOS Artwork Repository, use

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

728c6d
Convenction

Convenction

Do not freeze trunk development lines using tags

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

ed9de5
ed9de5

The trunk development line may introduce problems we cannot see

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

ed9de5

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

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

ed9de5

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

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

ed9de5

Before releasing a new major release of CentOS distribution we create

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

728c6d

ed9de5
ed9de5

2.67.2.4 Parallel directories

ed9de5
ed9de5

Inside CentOS Artwork Repository, parallel directories are simple

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

ed9de5

Parallel directories take their structure from one unique parent

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

ed9de5

In some circumstances, parallel directories may be created removing

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

ed9de5

Another example of parallel directory is the documentation structure

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

ed9de5

Othertimes, parallel directories may add uncommon information to their

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

ed9de5

When one parent directory changes, all their related parallel

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

728c6d

ed9de5
ed9de5

2.67.2.5 Syncronizing path information

ed9de5
ed9de5

Parallel directories are very useful to keep repository organized but

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

ed9de5

In such cases, functionalities like manual may confuse

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

ed9de5

In the specific case of documentation (the manual

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

ed9de5

There is no immediate way for manual, and similar

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

728c6d
Warning

Warning

There is not support for URL reference inside

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

ed9de5
ed9de5

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

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

ed9de5

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

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

728c6d

ed9de5
ed9de5

2.67.2.6 What is the right place to store it?

ed9de5
ed9de5

Occasionly, you may find that new corporate visual identity components

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

ed9de5

The CentOS Community different free support vains (see:

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

ed9de5

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

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

ed9de5

When building parent directory structures, you may find that reaching

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

ed9de5

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

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

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

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

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

728c6d

ed9de5
52772c

2.67.3 Usage

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

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

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

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

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

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

ed9de5
ed9de5
632e8b
728c6d

ed9de5
52772c

2.67.4 See also

632e8b
ed9de5
c8f7b7
2.60 The <tt>`trunk/Scripts'</tt> Directory  
ed9de5
ed9de5
632e8b
728c6d

632e8b
ed9de5
[ < ]
c8f7b7
[ > ]
632e8b
   
c8f7b7
[ << ]
ed9de5
[ Up ]
c8f7b7
[ >> ]
632e8b
632e8b
728c6d
            

728c6d
728c6d
        
728c6d
728c6d
    
728c6d
728c6d
    

728c6d
728c6d
728c6d
632e8b
</body>
728c6d
632e8b
</html>