Blame Manual/Directories/trunk/Scripts/Functions/Path.texi

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