@subsection Goals

This section exists to organize files related to @code{path}

functiontionality of @file{centos-art.sh} script.  The @code{path}

functionality of @file{centos-art.sh} script standardizes movement,

syncronization, branching, tagging, and general file maintainance

inside the repository. 

@subsection Description

@emph{''CentOS like trees, has roots, trunk, branches, leaves and

flowers.  Day by day they work together in freedom, ruled by the laws

of nature and open standards, to show the beauty of its

existence.''}

@subsubsection Repository layout

The repository layout describes organization of files and directories

inside the repository. The repository layout provides the standard

backend required for automation scripts to work correctly. If such

layout changes unexpectedly, automation scripts may confuse themselves

and stop doing what we expect from them to do.

As convenction, inside CentOS Artwork Repository, we organize files

and directories, related to CentOS corporate visual identity, under

three top level directories named @file{trunk/}, @file{branches/}, and

@file{tags/}. 

@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-6

@image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-6}

@caption{The CentOS Artwork Repository layout.}

@end float

The @file{trunk/} directory (@pxref{trunk}) organizes the main

development line of CentOS corporate visual identity. Inside

@file{trunk/} directory structure, the CentOS corporate visual

identity concepts are implemented using directories.  There is one

directory level for each relevant concept inside the repository. The

@file{trunk/} directory structure is mainly used to develop CentOS

corporate visual identity.

The @file{branches/} directory (@pxref{branches}) oranizes parallel

development lines to @file{trunk/} directory. The @file{branches/}

directory is used to set points in time where develpment lines are

devided one from another taking separte and idependent lives that

share a common past from the point they were devided on. The

@file{branches/} directory is mainly used to perform quality assurance

on CentOS corporate visual identity.

The @file{tags/} directory (@pxref{tags}) organizes parallel frozen

lines to @file{branches/} directory.  The parallel frozen lines are

immutable, nothing change inside them once they has been created.  The

@file{tags/} directory is mainly used to publish final releases of

CentOS corporate visual identity.

The CentOS Artwork Repository layout is firmly grounded on a

Subversion base.  Subversion (@url{http://subversion.tigris.org}) is a

version control system, which allows you to keep old versions of files

and directories (usually source code), keep a log of who, when, and

why changes occurred, etc., like CVS, RCS or SCCS.  Subversion keeps a

single copy of the master sources.  This copy  is called the source

``repository''; it contains all the information to permit extracting

previous versions of those files at any time.

@subsubsection Repository name convenctions

Repository name convenctions help us to maintain consistency of names

inside the repository.

Repository name convenctions are applied to files and directories

inside the repository layout. As convenction, inside the repository

layout, file names are all written in lowercase

(@samp{01-welcome.png}, @samp{splash.png}, @samp{anaconda_header.png},

etc.) and directory names are all written capitalized (e.g.,

@samp{Identity}, @samp{Themes}, @samp{Motifs}, @samp{TreeFlower},

etc.).

Repository name convenctions are implemented inside the

@code{cli_getRepoName} function of @file{centos-art.sh} script. With

@code{cli_getRepoName} function we reduce the amount of commands and

convenctions you need to remember concentrating them in just one

single place you can look for fixes and improvements.

@subsubsection Repository work flow

Repository work flow describes the steps and time intervals used to

produce CentOS corporate visual identity inside CentOS Artwork

Repository.  

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

cycle. 

Initially, we start working themes on their trunk development line

(e.g., @file{trunk/Identity/Themes/Motifs/TreeFlower/}), here we

design background images and propagate them to different visual

manifestations using one theme's model as reference.

Later, when the theme is considered ``ready'' for implementation (i.e.

all visual manifestations have been already set), we create a branch

for it (e.g., @file{branches/Identity/Themes/Motifs/TreeFlower/1/}).

Once the branch has been created, we forget that branch and continue

working the trunk development line while others (e.g., an artwork

quality assurance team) test the new branch for tunning it up. 

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

release, it is freezed under @file{tags/} directory (e.g.,

@file{tags/Identity/Themes/Motifs/TreeFower/1.0/}) for packagers,

webmasters, promoters, and anyone who needs images from that CentOS

theme the tag was created for.

Both branches and tags, inside CentOS Artwork Repository, use

numerical values to identify themselves under the same location.

Branches start at one (i.e., @samp{1}) and increment one unit for each

branch created from the same trunk development line.  Tags start at

zero (i.e., @samp{0}) and increment one unit for each tag created from

the same branch development line.

@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-1

@image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-1}

@caption{Name convention for tags and branches creation.}

@end float

As proposition, it would be convenient not to freeze trunk development

lines using tags or anything else.  If you think you need to freeze a

trunk development line, create a branch for it and then freeze that

branch instead.  

The trunk development line may introduce problems we cannot see

immediatly. Certainly, the high changable nature of trunk development

line complicates finding and fixing such problems. On the other hand,

the branched development lines provides a less changable area where

only small fixes/corrections are commited up to repository. 

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

could merge such changes/experiences back to trunk development line

(not visversa) in order for future branches, created from trunk, to

benefit.

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

different needs may arrive. For example, consider the release schema

of CentOS distribution: one major release every 2 years, security

updates every 6 months, support for 7 years long. Each time a CentOS

distribution is released, specially if it is a major release, there is

a theme need in order to cover CentOS distribution artwork

requirements. At this point, is where CentOS Artwork Repository comes

up to scene. 

Before releasing a new major release of CentOS distribution you can

create a branch for one of several theme development lines available

inside the CentOS Artwork Repository, perform quality assurance on it,

and later, freeze that branch using tags. Once a the theme branch has

been frozen (under @file{tags/} directory), CentOS Packagers (the

persons who build CentOS distribution) can use that frozen branch as

source location to fulfill CentOS distribution artwork needs.

@subsubsection Parallel directories

Inside CentOS Artwork Repository, parallel directories are simple

directory entries built from a common parent directory and placed in a

location different to that, the common parent directory is placed on.

Parallel directories are useful to create branches, tags,

translations, documentation, pre-rendering configuration script, and

similar directory structures.

Parallel directories take their structure from one unique parent

directory. Inside CentOS Artwork Repository, this unique parent

directory is under @file{trunk/Identity} location.  The

@file{trunk/Identity} location must be considered the reference for

whatever information you plan to create inside the repository.

In some circumstances, parallel directories may be created removing

uncommon information from their paths. Uncommon path information

refers to those directory levels in the path which are not common for

other parallel directories.  For example, when rendering

@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro} directory

structure, the @file{centos-art.sh} script removes the

@file{Motifs/TreeFlower/} directory levels from path, in order to

build the parallel directory used to retrived translations, and

pre-rendering configuration scripts required by @code{render}

functionality.

Another example where parallel directory removes the uncommon path

information is when we use the @code{help} functionality. This time,

@file{centos-art.sh} script uses parallel directory information

(without uncommon directory levels) to build the documentation entry

required by Texinfo to store documentation entries inside the

repository.

@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-3

@image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-3}

@caption{Parallel directories removing uncommon information.}

@end float

Othertimes, parallel directories may add uncommon information to their

paths. This is the case we use to create branches and tags. When we

create branches and tags, a numerical identifier is added to parallel

directory structure path. The place where the numerical identifier is

set on is relevant to corporate visual identity structure and should

be carefully considered where it will be.

@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-4

@image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-4}

@caption{Parallel directories adding uncommon information.}

@end float

When one parent directory changes, all their related parallel

directories need to be changed too. This is required in order for

parallel directories to match the new parent directory structure.  In

the other hand, parallel directories should never be modified by no

reason but to satisfy their parent directory structure. Liberal change

of parallel directories may suppress the conceptual idea they were

initially created for.

@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-5

@image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-5}

@caption{Wrong construction of parallel directories.}

@end float

@subsubsection Syncronizing path information

Creating parallel directories is very useful to keep repository

organized. But, what would happen to functionalities like @code{help}

(@pxref{trunk Scripts Bash Functions Help}) that rely on parent

directory structures to create documentation entries (using parallel

directory structures) if one of those parent directory structures

suddenly changes after the documentation entry has been already

created for it? 

Well, at this point, functionalities like @code{help} may confuse

themselves if path information is not updated.  Such functionalities

work with parent directory structure as reference; if a parent

directory changes, the functionalities dont't even note it because

they work with the last parent directory structure available in the

repository, no matter what it is. 

In the specific case of documentation (the @code{help} functionality),

the problem mentioned above provokes that older parent directories,

already documented, remain inside documentation directory structures

as long as you get your hands into the documentation directory

structure (@file{trunk/Manuals}) and remove what must be removed to

match the new parent directory structure.

There is no way for @code{help}, and similar functionalities that use

parent directories as reference, to know when and how directory

movements take place inside the repository. Such information is

available only when movement actions, like thoses achived by

@command{rm} or @command{mv} commands, take place inside the

repository. So, is there, at the moment of moving files, when we need

to syncronize parallel directories with their unique parent directory

structure.

Syncronizing parallel directories with their respecitive parent

directory implies moving files inside the repository, i.e. we need to,

firstly, rebuild the path information for each parallel directory

inside the repository, using the current path of its parent directory

as reference, and later, use the new path information to move each old

parallel directory from its old location to its new location based on

an updated path information.

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

file movements inside the repository are considered repository

changes. In order for these repository changes to be versioned, we

need to, firstly, add changes related files into version control

system, and later, use commands from the version control system to

move those files already versioned.  This configuration makes possible

for everyone to know about changes details inside the repository; and

if needed, revert or update them back to a previous revision.

Finally, once all file corrections have been already made, the

syncronization action takes care of updating path references inside

related files. Updating path references inside related files is

specially important for documentation files where documentation nodes

are built using repository path information as reference.

@subsubsection What is the right location to store it?

Occasionly, you may find that new corporate visual identity components

need to be added to the repository. If that is your case, the first

question you need to ask yourself, before start to create directories

blindly all over, is: What is the right location to store it?

The CentOS Community (@url{http://wiki.centos.org/GettingHelp}) is the

best place to find answers to your question, but going there with

hands empty is not good idea. It may give the impression you don't

really care about. Instead, consider the following suggestions to find

your own comprehension and so, make your propositions based on it.

When looking the correct place to store new files, to bear in mind the

corporate visual identity structure used inside the CentOS Artwork

Repository (@pxref{trunk Identity}) would be probaly the best advice

we could offer to you, the rest is just matter of choosing appropriate

names.  To illustrate this desition process let's consider the

@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro/} directory as

example. It is the main development line of CentOS distribution visual

manifestation, using TreeFlower's artistic motif, inside themes of

CentOS corporate visual identity. 

When building parent directory structures, you may find that reaching

an acceptable location may take some time, and as it happens most of

time, when you find it, that may be not a definite solution. There are

many concepts that you need to play with, in order to find a result

that match the conceptual idea you try to implement in the new

directory location. To know which these concepts are, split the

location in words and read its documentation entry from less specific

to more specific.

For example, the

@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro/} location

evolved through several months of contant work and there is no certain

it won't change in the future, even it fixes quite well the concept we

are trying to implement.  The concepts used in

@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower/Distro/} location

are described in the following commands, respectively:

@verbatim

centos-art help --read=turnk/

centos-art help --read=turnk/Identity/

centos-art help --read=turnk/Identity/Themes/

centos-art help --read=turnk/Identity/Themes/Motifs/

centos-art help --read=turnk/Identity/Themes/Motifs/TreeFlower/

centos-art help --read=turnk/Identity/Themes/Motifs/TreeFlower/Distro/

@end verbatim

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

change the location we used above by the one you are trying to know

concepts for.

@subsection Usage

@table @command

@item centos-art path --copy=SRC --to=DST

Use this command to duplicate @file{SRC} in working copy,

remembering history. In this command, @file{SRC} and

@file{DST} can each be either a working copy (WC) path or

URL:

@table @samp

@item WC -> WC

Copy and schedule for addition (with history).

@item WC -> URL

Immediately commit a copy of WC to URL.

@item URL -> WC

Check out URL into WC, schedule for addition.

@item URL -> URL

Complete server-side copy;  used to branch and tag.

@end table

This command is an interface for Subversion's @command{copy} command.

Options related to Subversion's @command{copy} command can be passed

from third argument on. For example to specify a log message use the

@option{--message} option as follow:

@verbatim

centos-art path --copy=URL/SRC --to=URL/DST --message 'Copy url/src to url/dst'

@end verbatim

For more information on Subversion's @command{copy} functionality,

run the command: @command{svn help copy | less}.

@item centos-art path --move=SRC --to=DST

Move and/or rename something in working copy or repository. In this

command, SRC and DST can both be working copy (WC) paths or URLs: 

@table @samp

@item WC -> WC

Move and schedule for addition (with history).

@item URL -> URL

Complete server-side rename.

@end table

This command is an interface for Subversion's @command{move} command.

Options related to Subversion's @command{move} command can be passed

from third argument on. For example to specify a log message use the

@option{--message} option as follow:

@verbatim

centos-art path --move=URL/SRC --to=URL/DST --message 'Move url/src to url/dst'

@end verbatim

For more information on Subversion's @command{move} functionality,

run the command: @command{svn help move | less}.

@item centos-art path --delete='SRC'

Use this command to remove files and directories from version control.

In this command, @file{SRC} can be a working copy (WC) path or URL. 

@table @samp

@item WC

Each item specified by a PATH is scheduled for deletion upon the next

commit.  Files, and directories that have not been committed, are

immediately removed from the working copy.  PATHs that are, or

contain, unversioned or modified items will not be removed unless the

@option{--force} option is given.

@item URL

Each item specified by a URL is deleted from the repository via an

immediate commit.

@end table

This command is an interface for Subversion's @command{delete}

command. Options related to Subversion's @command{delete} can be

passed from third argument on. For example to specify a log message

use the @option{--message} as follow:

@verbatim

centos-art path --delete='URL' --message 'Delete url.'

@end verbatim

For more information on Subversion's @command{delete} functionality,

run the command: @command{svn help delete | less}.

@item centos-art path --sync='SRC'

Use this command to syncronize path information inside working copy.

This command is automatically used after moving or renaming parent

directories.  In this command, @file{SRC} is a working copy path

inside @file{trunk/Identity/} location, considered the parent

directory you want to syncronize path information for.

@end table

@subsection See also

@menu

* trunk Scripts Bash::

* trunk Scripts Bash Functions::

@end menu