Blame Manuals/Repository/trunk/Scripts/Bash/Functions/Path.texi

ad1d7b
@subsection Goals
ad1d7b
ad1d7b
This section exists to organize files related to @code{path}
ad1d7b
functiontionality.  The @code{path} functionality standardizes
ad1d7b
movement, syncronization, branching, tagging, and general file
ad1d7b
maintainance inside the repository. 
ad1d7b
ad1d7b
@subsection Description
ad1d7b
ad1d7b
@emph{''CentOS like trees, has roots, trunk, branches, leaves and
ad1d7b
flowers.  Day by day they work together in freedom, ruled by the laws
ad1d7b
of nature and open standards, to show the beauty of its existence.''}
ad1d7b
ad1d7b
@subsubsection Repository layout
ad1d7b
ad1d7b
The repository layout describes organization of files and directories
ad1d7b
inside the repository. The repository layout provides the standard
ad1d7b
backend required for automation scripts to work correctly. If such
ad1d7b
layout changes unexpectedly, automation scripts may confuse themselves
ad1d7b
and stop doing what we expect from them to do.
ad1d7b
ad1d7b
As convenction, inside CentOS Artwork Repository, we organize files
ad1d7b
and directories related to CentOS corporate visual identity under
ad1d7b
three top level directories named: @file{trunk/}, @file{branches/},
ad1d7b
and @file{tags/}. 
ad1d7b
ad1d7b
@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-6
ad1d7b
@noindent @image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-6}
ad1d7b
@caption{The CentOS Artwork Repository layout.}
ad1d7b
@end float
ad1d7b
ad1d7b
The @file{trunk/} directory (@pxref{trunk}) organizes the main
ad1d7b
development line of CentOS corporate visual identity. Inside
ad1d7b
@file{trunk/} directory structure, the CentOS corporate visual
ad1d7b
identity concepts are implemented using directories.  There is one
ad1d7b
directory level for each relevant concept inside the repository. The
ad1d7b
@file{trunk/} directory structure is mainly used to perform
ad1d7b
development tasks related to CentOS corporate visual identity.
ad1d7b
ad1d7b
The @file{branches/} directory (@pxref{branches}) oranizes parallel
ad1d7b
development lines to @file{trunk/} directory. The @file{branches/}
ad1d7b
directory is used to set points in time where develpment lines are
ad1d7b
devided one from another taking separte and idependent lives that
ad1d7b
share a common past from the point they were devided on. The
ad1d7b
@file{branches/} directory is mainly used to perform quality assurance
ad1d7b
tasks related to CentOS corporate visual identity.
ad1d7b
ad1d7b
The @file{tags/} directory (@pxref{tags}) organizes parallel frozen
ad1d7b
lines to @file{branches/} directory.  The parallel frozen lines are
ad1d7b
immutable, nothing change inside them once they has been created.  The
ad1d7b
@file{tags/} directory is mainly used to publish final releases of
ad1d7b
CentOS corporate visual identity.
ad1d7b
ad1d7b
The CentOS Artwork Repository layout is firmly grounded on a
ad1d7b
Subversion base.  Subversion (@url{http://subversion.tigris.org}) is a
ad1d7b
version control system, which allows you to keep old versions of files
ad1d7b
and directories (usually source code), keep a log of who, when, and
ad1d7b
why changes occurred, etc., like CVS, RCS or SCCS.  Subversion keeps a
ad1d7b
single copy of the master sources.  This copy  is called the source
ad1d7b
``repository''; it contains all the information to permit extracting
ad1d7b
previous versions of those files at any time.
ad1d7b
ad1d7b
@subsubsection Repository name convenctions
ad1d7b
ad1d7b
Repository name convenctions help us to maintain consistency of names
ad1d7b
inside the repository.
ad1d7b
ad1d7b
Repository name convenctions are applied to files and directories
ad1d7b
inside the repository layout. As convenction, inside the repository
ad1d7b
layout, file names are all written in lowercase
ad1d7b
(@samp{01-welcome.png}, @samp{splash.png}, @samp{anaconda_header.png},
ad1d7b
etc.) and directory names are all written capitalized (e.g.,
ad1d7b
@samp{Identity}, @samp{Themes}, @samp{Motifs}, @samp{TreeFlower},
ad1d7b
etc.).
ad1d7b
ad1d7b
Repository name convenctions are implemented inside the
ad1d7b
@code{cli_getRepoName} function of @file{centos-art.sh} script. With
ad1d7b
@code{cli_getRepoName} function we reduce the amount of commands and
ad1d7b
convenctions to remember, concentrating them in just one single place
ad1d7b
to look for fixes and improvements.
ad1d7b
ad1d7b
@subsubsection Repository work flow
ad1d7b
ad1d7b
Repository work flow describes the steps and time intervals used to
ad1d7b
produce CentOS corporate visual identity inside CentOS Artwork
ad1d7b
Repository.  
ad1d7b
ad1d7b
To illustrate repository work flow let's consider themes' development
ad1d7b
cycle. 
ad1d7b
ad1d7b
Initially, we start working themes on their trunk development line
ad1d7b
(e.g., @file{trunk/Identity/Themes/Motifs/TreeFlower/}), here we
ad1d7b
organize information that cannot be produced automatically (i.e.,
ad1d7b
background images, concepts, color information, screenshots, etc.).
ad1d7b
ad1d7b
Later, when theme trunk development line is considered ``ready'' for
ad1d7b
implementation (e.g.,  all required backgrounds have been designed),
ad1d7b
we create a branch for it (e.g.,
ad1d7b
@file{branches/Identity/Themes/Motifs/TreeFlower/1/}).  Once the
ad1d7b
branch has been created, we forget that branch and continue working
ad1d7b
the trunk development line while others (e.g., an artwork quality
ad1d7b
assurance team) test the new branch for tunning it up. 
ad1d7b
ad1d7b
Once the branch has been tunned up, and considered ``ready'' for
ad1d7b
release, it is freezed under @file{tags/} directory (e.g.,
ad1d7b
@file{tags/Identity/Themes/Motifs/TreeFower/1.0/}) for packagers,
ad1d7b
webmasters, promoters, and anyone who needs images from that CentOS
ad1d7b
theme the tag was created for.
ad1d7b
ad1d7b
Both branches and tags, inside CentOS Artwork Repository, use
ad1d7b
numerical values to identify themselves under the same location.
ad1d7b
Branches start at one (i.e., @samp{1}) and increment one unit for each
ad1d7b
branch created from the same trunk development line.  Tags start at
ad1d7b
zero (i.e., @samp{0}) and increment one unit for each tag created from
ad1d7b
the same branch development line.
ad1d7b
ad1d7b
@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-1
ad1d7b
@noindent @image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-1,400pt}
ad1d7b
@caption{Name convention for tags and branches creation.}
ad1d7b
@end float
ad1d7b
ad1d7b
@quotation
ad1d7b
@strong{Convenction} Do not freeze trunk development lines using tags
ad1d7b
directly.  If you think you need to freeze a trunk development line,
ad1d7b
create a branch for it and then freeze that branch instead.
ad1d7b
@end quotation
ad1d7b
ad1d7b
The trunk development line may introduce problems we cannot see
ad1d7b
immediatly. Certainly, the high changable nature of trunk development
ad1d7b
line complicates finding and fixing such problems. On the other hand,
ad1d7b
the branched development lines provide a more predictable area where
ad1d7b
only fixes/corrections to current content are commited up to
ad1d7b
repository. 
ad1d7b
ad1d7b
If others find and fix bugs inside the branched development line, we
ad1d7b
could merge such changes/experiences back to trunk development line
ad1d7b
(not visversa) in order for future branches, created from trunk, to
ad1d7b
benefit.
ad1d7b
ad1d7b
Time intervals used to create branches and tags may vary, just as
ad1d7b
different needs may arrive. For example, consider the release schema
ad1d7b
of CentOS distribution: one major release every 2 years, security
ad1d7b
updates every 6 months, support for 7 years long. Each time a CentOS
ad1d7b
distribution is released, specially if it is a major release, there is
ad1d7b
a theme need in order to cover CentOS distribution artwork
ad1d7b
requirements. At this point, is where CentOS Artwork Repository comes
ad1d7b
up to scene. 
ad1d7b
ad1d7b
Before releasing a new major release of CentOS distribution we create
ad1d7b
a branch for one of several theme development lines available inside
ad1d7b
the CentOS Artwork Repository, perform quality assurance on it, and
ad1d7b
later, freeze that branch using tags. Once a the theme branch has been
ad1d7b
frozen (under @file{tags/} directory), CentOS Packagers (the persons
ad1d7b
whom build CentOS distribution) can use that frozen branch as source
ad1d7b
location to fulfill CentOS distribution artwork needs. The same
ad1d7b
applies to CentOS Webmasters (the persons whom build CentOS websites),
ad1d7b
and any other visual manifestation required by the project.
ad1d7b
ad1d7b
@subsubsection Parallel directories
ad1d7b
ad1d7b
Inside CentOS Artwork Repository, parallel directories are simple
ad1d7b
directory entries built from a common parent directory and placed in a
ad1d7b
location different to that, the common parent directory is placed on.
ad1d7b
Parallel directories are useful to create branches, tags,
ad1d7b
translations, documentation, pre-rendering configuration script, and
ad1d7b
similar directory structures.
ad1d7b
ad1d7b
Parallel directories take their structure from one unique parent
ad1d7b
directory. Inside CentOS Artwork Repository, this unique parent
ad1d7b
directory is under @file{trunk/Identity} location.  The
ad1d7b
@file{trunk/Identity} location must be considered the reference for
ad1d7b
whatever information you plan to create inside the repository.
ad1d7b
ad1d7b
In some circumstances, parallel directories may be created removing
ad1d7b
uncommon information from their paths. Uncommon path information
ad1d7b
refers to those directory levels in the path which are not common for
ad1d7b
other parallel directories.  For example, when rendering
ad1d7b
@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro} directory
ad1d7b
structure, the @file{centos-art.sh} script removes the
ad1d7b
@file{Motifs/TreeFlower/} directory levels from path, in order to
ad1d7b
build the parallel directory used to retrived translations, and
ad1d7b
pre-rendering configuration scripts required by @code{render}
ad1d7b
functionality.
ad1d7b
ad1d7b
@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-3
ad1d7b
@noindent @image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-3,400pt}
ad1d7b
@caption{Parallel directories removing uncommon information.}
ad1d7b
@end float
ad1d7b
ad1d7b
Another example of parallel directory is the documentation structure
ad1d7b
created by @code{manual} functionality. This time,
ad1d7b
@file{centos-art.sh} script uses parallel directory information with
ad1d7b
uncommon directory levels to build the documentation entry required by
ad1d7b
Texinfo documentation system, inside the repository.
ad1d7b
ad1d7b
Othertimes, parallel directories may add uncommon information to their
ad1d7b
paths. This is the case we use to create branches and tags. When we
ad1d7b
create branches and tags, a numerical identifier is added to parallel
ad1d7b
directory structure path. The place where the numerical identifier is
ad1d7b
set on is relevant to corporate visual identity structure and should
ad1d7b
be carefully considered where it will be.
ad1d7b
ad1d7b
@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-4
ad1d7b
@noindent @image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-4,400pt}
ad1d7b
@caption{Parallel directories adding uncommon information.}
ad1d7b
@end float
ad1d7b
ad1d7b
When one parent directory changes, all their related parallel
ad1d7b
directories need to be changed too. This is required in order for
ad1d7b
parallel directories to retain their relation with the parent
ad1d7b
directory structure.  In the other hand, parallel directories should
ad1d7b
never be modified under no reason but to satisfy the relation to their
ad1d7b
parent directory structure.  Liberal change of parallel directories
ad1d7b
may suppresses the conceptual idea they were initially created for;
ad1d7b
and certainly, things may stop working the way they should do.
ad1d7b
ad1d7b
@float Figure, trunk/Identity/Models/Img/Scripts/Bash/Functions/Paths/figure-5
ad1d7b
@noindent @image{trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-5,400pt}
ad1d7b
@caption{Wrong construction of parallel directories.}
ad1d7b
@end float
ad1d7b
ad1d7b
@subsubsection Syncronizing path information
ad1d7b
ad1d7b
Parallel directories are very useful to keep repository organized but
ad1d7b
introduce some complications.  For instance, consider what would
ad1d7b
happen to functionalities like @code{manual} (@samp{trunk Scripts Bash
ad1d7b
Functions Manual}) that rely on parent directory structures to create
ad1d7b
documentation entries (using parallel directory structures) if one of
ad1d7b
those parent directory structures suddenly changes after the
ad1d7b
documentation entry has been already created for it? 
ad1d7b
ad1d7b
In such cases, functionalities like @code{manual} may confuse
ad1d7b
themselves if path information is not updated to reflect the relation
ad1d7b
with its parent directory.  Such functionalities work with parent
ad1d7b
directory structure as reference; if a parent directory changes, the
ad1d7b
functionalities dont't even note it because they work with the last
ad1d7b
parent directory structure available in the repository, no matter what
ad1d7b
it is. 
ad1d7b
ad1d7b
In the specific case of documentation (the @code{manual}
ad1d7b
functionality), the problem mentioned above provokes that older parent
ad1d7b
directories, already documented, remain inside documentation directory
ad1d7b
structures as long as you get your hands into the documentation
ad1d7b
directory structure (@file{trunk/Manuals}) and change what must be
ad1d7b
changed to match the new parent directory structure.
ad1d7b
ad1d7b
There is no immediate way for @code{manual}, and similar
ad1d7b
functionalities that use parent directories as reference, to know when
ad1d7b
and how directory movements take place inside the repository. Such
ad1d7b
information is available only when the file movement itself takes
ad1d7b
place inside the repository. So, is there, at the moment of moving
ad1d7b
files, when we need to syncronize parallel directories with their
ad1d7b
unique parent directory structure.
ad1d7b
ad1d7b
@quotation
ad1d7b
@strong{Warning} There is not support for URL reference inside
ad1d7b
@file{centos-art.sh} script.  The @file{centos-art.sh} script is
ad1d7b
designed to work with local files inside the working copy only.
ad1d7b
@end quotation
ad1d7b
ad1d7b
As CentOS Artwork Repository is built over a version control system,
ad1d7b
file movements inside the repository are considered repository
ad1d7b
changes. In order for these repository changes to be versioned, we
ad1d7b
need to, firstly, add changes into the version control system, commit
ad1d7b
them, and later, perform movement actions using version control system
ad1d7b
commands. This configuration makes possible for everyone to know about
ad1d7b
changes details inside the repository; and if needed, revert or update
ad1d7b
them back to a previous revision.
ad1d7b
ad1d7b
Finally, once all path information has been corrected, it is time to
ad1d7b
take care of information inside the files. For instance, considere
ad1d7b
what would happen if you make a reference to a documentation node, and
ad1d7b
later the documentation node you refere to is deleted. That would make
ad1d7b
Texinfo to produce error messages at export time. So, the
ad1d7b
@file{centos-art.sh} script needs to know when such changes happen, in
ad1d7b
a way they could be noted and handled without producing errors.
ad1d7b
ad1d7b
@subsubsection What is the right place to store it?
ad1d7b
ad1d7b
Occasionly, you may find that new corporate visual identity components
ad1d7b
need to be added to the repository. If that is your case, the first
ad1d7b
question you need to ask yourself, before start to create directories
ad1d7b
blindly all over, is: What is the right place to store it?
ad1d7b
ad1d7b
The CentOS Community different free support vains (see:
ad1d7b
@url{http://wiki.centos.org/GettingHelp}) are the best place to find
ad1d7b
answers to your question, but going there with hands empty is not good
ad1d7b
idea. It may give the impression you don't really care about. Instead,
ad1d7b
consider the following suggestions to find your own comprehension and
ad1d7b
so, make your propositions based on it.
ad1d7b
ad1d7b
When we are looking for the correct place to store new files, to bear
ad1d7b
in mind the corporate visual identity structure used inside the CentOS
ad1d7b
Artwork Repository (@pxref{trunk Identity}) would be probaly the best
ad1d7b
advice we could offer, the rest is just matter of choosing appropriate
ad1d7b
names.  To illustrate this desition process let's consider the
ad1d7b
@file{trunk/Identity/Themes/Motifs/TreeFlower} directory as example.
ad1d7b
It is the trunk development line of @emph{TreeFlower} artistic motif.
ad1d7b
Artistic motifs are considered part of themes, which in turn are
ad1d7b
considered part of CentOS corporate visual identity.
ad1d7b
ad1d7b
When building parent directory structures, you may find that reaching
ad1d7b
an acceptable location may take some time, and as it uses to happen
ad1d7b
most of time; once you've find it, that may be not a definite
ad1d7b
solution.  There are many concepts that you need to play with, in
ad1d7b
order to find a result that match the conceptual idea you try to
ad1d7b
implement in the new directory location. To know which these concepts
ad1d7b
are, split the location in words and read its documentation entry from
ad1d7b
less specific to more specific.
ad1d7b
ad1d7b
For example, the @file{trunk/Identity/Themes/Motifs/TreeFlower}
ad1d7b
location evolved through several months of contant work and there is
ad1d7b
no certain it won't change in the future, even it fixes quite well the
ad1d7b
concept we are trying to implement.  The concepts used in
ad1d7b
@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} location are
ad1d7b
described in the following commands, respectively:
ad1d7b
ad1d7b
@verbatim
ad1d7b
centos-art manual --read=turnk/
ad1d7b
centos-art manual --read=turnk/Identity/
ad1d7b
centos-art manual --read=turnk/Identity/Themes/
ad1d7b
centos-art manual --read=turnk/Identity/Themes/Motifs/
ad1d7b
centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/
ad1d7b
@end verbatim
ad1d7b
ad1d7b
Other location concepts can be found similary as we did above, just
ad1d7b
change the location we used above by the one you are trying to know
ad1d7b
concepts for.
ad1d7b
ad1d7b
@subsection Usage
ad1d7b
ad1d7b
@table @command
ad1d7b
@item centos-art path --copy='SRC' --to='DST'
ad1d7b
ad1d7b
Copy @option{SRC} to @option{DST} and schedule @option{DST} for
ad1d7b
addition (with history).  In this command, @file{SRC} and @file{DST}
ad1d7b
are both working copy (WC) entries.
ad1d7b
ad1d7b
@item centos-art path --delete='SRC'
ad1d7b
ad1d7b
Delete @option{DST}. In order for this command to work the file or
ad1d7b
directory you intend to delete should be under version control first.
ad1d7b
In this command, @file{SRC} is a working copy (WC) entry.  
ad1d7b
ad1d7b
@end table
ad1d7b
ad1d7b
@subsection See also
ad1d7b
ad1d7b
@menu
ad1d7b
* trunk Scripts Bash::
ad1d7b
* trunk Scripts Bash Functions::
ad1d7b
@end menu