<chapter id="intro-usage" xreflabel="Usage convenctions">
<title>Usage convenctions</title>
<para>The CentOS Artwork Repository is supported by Subversion
(http://subversion.tigris.org/), 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.</para>
<para>When using Subversion there is one "source repository" and
many "working copies" of that source repository. The working
copies are independent one another, can be distributed all around
the world and provide a local place for designers, documentors,
translators and programmers to perform their work in a
descentralized way. The source repository, on the other hand,
provides a central place for all independent working copies to
interchange data and provides the information required to permit
extracting previous versions of files at any time.</para>
<sect1 id="repo-usage-policy" xreflabel="Policy">
<title>Policy</title>
<para>The CentOS Artwork Repository is a collaborative tool
that anyone can have access to. However, changing that tool in
any form is something that should be requested in the CentOS
Developers mailing list (centos-devel@centos.org). Generally,
people download working copies from CentOS Artwork Repository,
study the repository organization, make some changes in their
working copies, make some tests to verify such changes do work
the way expected and finally request access to commit them up
to the CentOS Artwork Repository (i.e., the source repository)
for others to benefit from them.</para>
<para>Once you've received access to commit your changes,
there is no need for you to request permission again to commit
other changes from your working copy to CentOS Artwork
Repository as long as you behave as a <emphasis>good
cooperating citizen</emphasis>. Otherwise, your rights to
commit changes might be temporarly revoked or permanently
banished.</para>
<para>As a good cooperating citizen one understand of a person
who respects the work already done by others and share ideas
with authors before changing relevant parts of their work,
specially in situations when the access required to realize
the changes has been granted already. Of course, there is a
time when conversation has taken place, the paths has been
traced and changing the work is so obvious that there is no
need for you to talk about it; that's because you already did,
you already built the trust to keep going. Anyway, the mailing
list mentioned above is available for sharing ideas in a way
that good relationship between community citizens could be
constantly balanced.</para>
<para>The relationship between community citizens is monitored
by repository administrators. Repository administrators are
responsible of granting that everything goes the way it needs
to go in order for the CentOS Artwork Repository to accomplish
its mission which is: to provide a colaborative tool for The
CentOS Community where The CentOS Project corporate visual
identity is built and maintained by The CentOS Community
itself.</para>
<para>It is also important to remember that all the program
and documentation source files inside CentOS Artwork
Repository must comply the terms of <xref
linkend="licenses-gpl" /> and <xref linkend="licenses-gfdl" />
respectively in order for them to remain inside the
repository.</para>
</sect1>
<sect1 id="intro-usage-worklines" xreflabel="Worklines">
<title>Work lines</title>
<para>Content production inside the repository is organized by
<emphasis>work lines</emphasis>. There are three major work
lines of production inside The CentOS Artwork Repository,
which are: <emphasis>Graphic design</emphasis>,
<emphasis>Documentation</emphasis> and
<emphasis>Localization</emphasis>. The specific way of
producing content inside each specific work line is
standardized by mean of <command>centos-art.sh</command>
script (which in turn, can be considered a work line by itself
[e.g., the <emphasis>Automation</emphasis> work line]). The
<command>centos-art.sh</command> script provides one specific
functionality for automating each major work line of content
production (e.g., <code>render</code> for producing images,
<code>help</code> for manage documentation, and
<code>locale</code> for localizing contents).</para>
<para>The graphic design work line exists to cover brand
design, typography design and themes design mainly.
Additionally, some auxiliar areas like icon design,
illustration design, brushes design, patterns designs and
palettes of colors are also included here for completeness.
The graphic design work line is organized in the <filename
class="directory">trunk/Identity</filename> directory.</para>
<para>The documentation work line exists to describe what each
directory inside the CentOS Artwork Repository is for, the
conceptual ideas behind them and, if possible, how automation
scripts make use of them. The documentation work line is
organized in the <filename
class="directory">trunk/Manuals</filename> directory.</para>
<para>The localization work line exists to provide the
translation messages required to produce content in different
languages. Translation messages inside the repository are
stored as portable objects (e.g., .po, .pot) and machine
objects (.mo). The localization work line is organized in the
<filename class="directory">trunk/Locales</filename>
directory.</para>
<para>The automation work line exists to standardize content
production inside the working copies of CentOS Artwork
Repository. Here is developed the
<command>centos-art.sh</command> script, a bash script
specially designed to automate most frequent tasks (e.g.,
rendition, documentation and localization) inside the
repository. There is no need to type several tasks, time
after time, if they can be programmed into just one executable
script. The automation work line is organized in the
<filename class="directory">trunk/Scripts</filename>
directory.</para>
</sect1>
<sect1 id="intro-usage-conbdirs" xreflabel="Relation between directories">
<title>Relation between directories</title>
<para>In order for automation scripts to produce content inside a
working copy of CentOS Artwork Repository, it is required that all
work lines be related somehow. The relation is used by automation
scripts to know where to retrive the information they need to work
with (e.g., design model, translation messages, output locations,
etc.). This kind of relation is built using two path
constructions named <emphasis>master paths</emphasis> and
<emphasis>auxiliar paths</emphasis>.</para>
<para>The master path points only to directories that contain
source files (e.g., SVG files) required to produce output base
content (e.g., PNG files) through automation scripts. Each master
path inside the repository may have several auxiliar paths
associated, but auxiliar paths can only have one master path
associated.</para>
<para>Master paths used for producing images through SVG rendition
are organized under <filename
class="directory">trunk/Identity/Models</filename> directory
structure and the auxiliar paths under <filename
class="directory">trunk/Identity/Images</filename>, <filename
class="directory">trunk/Locales</filename> and <filename
class="directory">trunk/Manuals</filename> directory
structures.</para>
<para>Auxiliar paths can point either to directories or files.
When an auxiliar path points to a directory, that directory
contains information that modifies somehow the content produced
from master paths (e.g., translation messages) or provides the
output information required to know where the content produced
from the master path should be stored. When an auxiliar path
points to a file, that file has no other purpose but to document
the master path it refers to.</para>
<para>Auxiliar paths should never be modified under any reason but
to satisfy the relationship with the master path. Liberal change
of auxiliar paths may suppress the conceptual idea they were
initially created for; and certainly, automation scripts may stop
working as expected.</para>
<para>The relationship between auxiliar paths and master paths is
built by combining the master path and the second level directory
structures of the repository. The master path is considered the
path identifier and the repository second level directory
structure is considered the common part of the path where the path
identifier is appended to. So, if we have the master path
<filename
class="directory">trunk/Identity/Models/Brands</filename>, we'll
end up having, at least, the <filename
class="directory">trunk/Identity/Images/Brands</filename> auxiliar
path for storing output files and, optionally, one path under
<filename class="directory">trunk/Manuals</filename> for storing
documentation and one path under <filename
class="directory">trunk/Locales</filename> for storing
localizations.</para>
</sect1>
<sect1 id="intro-usage-syncro" xreflabel="Syncronizing paths">
<title>Syncronizing paths</title>
<para>Once both master paths and their auxiliar paths have been
set, they shouldn't be changed. Assuming one master path must be
changed it is required that all related auxiliar paths be changed,
too. This is required in order for master paths to retain their
relation with auxiliar paths. This process of keeping relation
between master paths and auxiliar paths is known as <emphasis>path
syncronization</emphasis>. </para>
<para>Path syncronization is required for automation scripts to
know where to store final output, where to retrive translation
messages, documentation, and any information that might be
desired. If the relation between master paths and auxiliar paths
is lost, there is no way for <command>centos-art.sh</command>
script to know where to retrive the information it needs to work
with. Path syncronization is the way we use to organize and
extend the information stored in the repository.</para>
<para>Path syncronization may imply both movement of files and
replacement of content inside files. Movement of files is related
to actions like renaming files and directories inside the
repository. Replacement of content inside files is related to
actions like replacing information (e.g., paths information)
inside files in order to keep file contents and file locations
consistent one another.</para>
<para>The order followed to syncronize path information is very
important because the versioned nature of the repository files we
are working with. When a renaming action must be performed, we
avoid making replacements inside files first and file movements
later. This would require two commit actions: one for the files'
internal changes and another for the file movement itself.
Otherwise, we prefer to perform file movements first and file
internal replacements later. This way it is possible to commit
both changes as if they were just one.</para>
<warning><para>There is no support for URLs actions inside
<command>centos-art.sh</command> script. The
<command>centos-art.sh</command> script is designed to work with
local files inside the working copy only. If you need to perform
URL actions directly, use Subversion commands
instead.</para></warning>
<para>At this moment there is no full implementation of path
syncronization process inside <command>centos-art.sh</command>
script except by <quote>texinfo</quote> backend of
<code>help</code> functionality which provides a restricted
implementation of path syncronization to this specific area of
documentation through the <option>--copy</option>,
<option>--delete</option> and <option>--rename</option> options.
The plan for a full implementation of path syncronization would be
to create individual restricted implementations like this one for
other areas that demand it and then, create a higher implmentation
that combines all restricted implementations as needed. This way,
if we try to rename a repository directory the higer action will
define which are all the restricted actions that should be
performed in order for make a full path syncronization. For
example, if the directory we are renaming is part of graphic
design work line, it is required to syncronize related paths in
documentation and localization work lines. Likewise, if the
directory we are renaming is in documentation work line, it is
required to syncronize related paths in graphic design and
localization work lines. In all these cases, the direction used
for syncronizing paths must be from master path to auxiliar path
and never the opposite (i.e., rename the master path first and
auxiliar paths later).</para>
<para>A practical example, through which you can notice the
usefulness of path syncronization process, is what happen when
documentation entries are renamed (see section ...).</para>
</sect1>
<sect1 id="intro-usage-extending" xreflabel="Extending repository
organization">
<title>Extending repository organization</title>
<para>Occasionly, you may find that new components of The
CentOS Project corporate visual identity need to be added to
the repository in order to work them out. If that is the case,
the first question we need to ask ourselves, before start to
create directories blindly all over, is: <emphasis>What is the
right place to store it?</emphasis></para>
<para>The best place to find answers is in The CentOS
Community (see page http://wiki.centos.org/Help), 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 in order
to make your own propositions based on it.</para>
<para>When extending respository structure it is very useful
to bear in mind The CentOS Project corporate visual identity
structure, The CentOS Mission and The CentOS Release Schema.
The rest is a matter of choosing appropriate names. It is also
worth to know that each directory in the repository responds
to a conceptual idea that justifies its existence.</para>
<para>To build a directory structure inside the repository,
you need to define the conceptual idea first and later create
the directory, remembering that there are locations inside the
repository that define conceptual ideas you probably would
prefer to reuse. For example, the <filename
class="directory">trunk/Identity/Images/Themes</filename>
directory stores theme artistic motifs, the <filename
class="directory">trunk/Identity/Models/Themes</filename>
directory stores theme design models, the <filename
class="directory">trunk/Manuals</filename> directory stores
documentation files, the <filename
class="directory">trunk/Locales</filename> stores translation
messages, and the <filename
class="directory">trunk/Scripts</filename> stores automation
scripts.</para>
<para>To better illustrate this desition process, you can
consider to examin the <filename
class="directory">trunk/Identity/Images/Themes/TreeFlower/3</filename>
directory structure as example. This directory can be read
as: the theme development line of version <quote>3</quote> of
<quote>TreeFlower</quote> artistic motif. Additional, we can
say that <quote>TreeFlower</quote> artistic motif is part of
themes, as themes are part of The CentOS Project corporate
visual identity.</para>
<para>The relationship between conceptual ideas can be
stablished by reading each repository documentation entry
individually, from <filename
class="directory">trunk</filename> directory to a deeper
directory in the path. For reading repository documentation
entries we use the <code>help</code> functionality of
<command>centos-art.sh</command> script.</para>
</sect1>
<sect1 id="intro-usage-filenames" xreflabel="File names convenction">
<title>File names convenction</title>
<para>Inside the CentOS Artwork Repository, generally, file
names are all written in lowercase (e.g.,
<filename>01-welcome.png</filename>,
<filename>splash.png</filename>,
<filename>anaconda_header.png</filename>, etc.) and directory
names are all written capitalized (e.g., <filename
role="directory">Identity</filename>, <filename
role="directory">Themes</filename>, <filename
role="directory">Motifs</filename>) and sometimes in cammel
case (e.g., <filename role="directory">TreeFlower</filename>,
etc.). </para>
<para>In the very specific case of repository documentation
entries, file names follow the directory naming convenction.
This is because they are documenting directories and that is
something we want to remark. So, to better describe what we
are documenting, documentation entries follow the name
convenction used by the item they document.</para>
</sect1>
<sect1 id="intro-usage-layout" xreflabel="Repository layout">
<title>Repository layout</title>
<para>The CentOS Artwork Repository is organized through a
convenctional <quote>trunk</quote>, <quote>branches</quote>
and <quote>tags</quote> layout. Explanation of each directory
inside the repository can be found in the <xref
linkend="directories" /> chapter.</para>
</sect1>
</chapter>