Goals
-----

This section exists to organize files related to path functiontionality of centos-art.sh script.  The path functionality of centos-art.sh script standardizes movement, syncronization, branching, tagging, and general file maintainance inside the repository.

Description
-----------

''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.''

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 trunk/, branches/, and tags/.

Figure: The CentOS Artwork Repository layout.

The trunk/ directory (see trunk) organizes the main development line of CentOS corporate visual identity. Inside 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 trunk/ directory structure is mainly used to develop CentOS corporate visual identity.

The branches/ directory (see branches) oranizes parallel development lines to trunk/ directory. The 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 branches/ directory is mainly used to perform quality assurance on CentOS corporate visual identity.

The tags/ directory (see tags) organizes parallel frozen lines to branches/ directory.  The parallel frozen lines are immutable, nothing change inside them once they has been created.  The 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 (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.

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 (01-welcome.png, splash.png, anaconda_header.png, etc.) and directory names are all written capitalized (e.g., Identity, Themes, Motifs, TreeFlower, etc.).

Repository name convenctions are implemented inside the cli_getRepoName function of centos-art.sh script. With 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.

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., 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., 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 tags/ directory (e.g., 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., 1) and increment one unit for each branch created from the same trunk development line.  Tags start at zero (i.e., 0) and increment one unit for each tag created from the same branch development line.

Figure: Name convention for tags and branches creation.

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 tags/ directory), CentOS Packagers (the persons who build CentOS distribution) can use that frozen branch as source location to fulfill CentOS distribution artwork needs.

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 trunk/Identity location.  The 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 trunk/Identity/Themes/Motifs/TreeFlower/Distro directory structure, the centos-art.sh script removes the Motifs/TreeFlower/ directory levels from path, in order to build the parallel directory used to retrived translations, and pre-rendering configuration scripts required by render functionality.

Another example where parallel directory removes the uncommon path information is when we use the help functionality. This time, 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.

Figure: Parallel directories removing uncommon information.

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.

Figure: Parallel directories adding uncommon information.

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.

Figure: Wrong construction of parallel directories.

Syncronizing path information
.............................

Creating parallel directories is very useful to keep repository organized. But, what would happen to functionalities like help (WARNING: The trunk Scripts Bash Functions Help documentation entry no longer exists.) 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 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 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 (trunk/Manuals) and remove what must be removed to match the new parent directory structure.

There is no way for 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 rm or 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.

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 (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 (see 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 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 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 trunk/Identity/Themes/Distro/Motifs/TreeFlower/Distro/ location are described in the following commands, respectively:

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/

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.

Usage
-----

centos-art path --copy=SRC --to=DST
     Use this command to duplicate SRC in working copy, remembering history. In this command, SRC and DST can each be either a working copy (WC) path or URL:

     WC -> WC
          Copy and schedule for addition (with history).

     WC -> URL
          Immediately commit a copy of WC to URL.

     URL -> WC
          Check out URL into WC, schedule for addition.

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

     This command is an interface for Subversion's copy command. Options related to Subversion's copy command can be passed from third argument on. For example to specify a log message use the --message option as follow:

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

     For more information on Subversion's copy functionality, run the command: svn help copy | less.

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:

     WC -> WC
          Move and schedule for addition (with history).

     URL -> URL
          Complete server-side rename.

     This command is an interface for Subversion's move command. Options related to Subversion's move command can be passed from third argument on. For example to specify a log message use the --message option as follow:

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

     For more information on Subversion's move functionality, run the command: svn help move | less.

centos-art path --delete='SRC'
     Use this command to remove files and directories from version control. In this command, SRC can be a working copy (WC) path or URL.

     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 --force option is given.

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

     This command is an interface for Subversion's delete command. Options related to Subversion's delete can be passed from third argument on. For example to specify a log message use the --message as follow:

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

     For more information on Subversion's delete functionality, run the command: svn help delete | less.

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, SRC is a working copy path inside trunk/Identity/ location, considered the parent directory you want to syncronize path information for.

See also
--------