Blob Blame History Raw
The CentOS Artwork Repository is supported by Subversion
(@url{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.

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.

@subheading Policy
@cindex Policy

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
(@email{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.

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
good cooperating citizen. Otherwise, your rights to commit changes
might be temporarly revoked or permanently banished.

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.

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.

It is also important to remember that all the program and
documentation source files inside CentOS Artwork Repository must
comply the terms of @ref{GNU General Public License} and @ref{GNU Free
Documentation License} respectively in order for them to remain inside
the repository.

@subheading Work lines
@cindex Work lines

Content production inside the repository is organized by work lines.
There are three major work lines of production inside The CentOS
Artwork Repository, which are: Graphic design, Documentation and
Localization. The specific way of producing content inside each
specific work line is standardized by mean of centos-art.sh  script
(which in turn, can be considered a work line by itself [e.g., the
Automation work line]). The centos-art.sh script provides one specific
functionality for automating each major work line of content
production (e.g., render for producing images, help for manage
documentation, and locale for localizing contents).

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
@xref{Directories trunk Identity}.

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 @xref{Directories
trunk Manuals}.

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 @xref{Directories trunk Manuals}.

The automation work line exists to standardize content production
inside the working copies of CentOS Artwork Repository. Here is
developed the centos-art.sh 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
@pxref{Directories trunk Manuals}.

@subheading Relation between directories
@cindex Relation between directories
@cindex Master paths
@cindex Auxiliar paths

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 ``master paths''
and ``auxiliar paths''.

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.

Master paths used for producing images through SVG rendition are
organized under @file{trunk/Identity/Models} directory structure and
the auxiliar paths under @file{trunk/Identity/Images},
@file{trunk/Locales} and @file{trunk/Manuals} directory structures.

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.

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.

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 @file{trunk/Identity/Models/Brands}, we'll
end up having, at least, the @file{trunk/Identity/Images/Brands}
auxiliar path for storing output files and, optionally, one path under
trunk/Manuals for storing documentation and one path under
@file{trunk/Locales} for storing localizations.

@subheading Syncronizing path information
@cindex Syncronizing path information

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 path syncronization.

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 centos-art.sh 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.

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.

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.

@quotation
@strong{Warning} There is no support for URLs actions inside
@command{centos-art.sh} script. The @command{centos-art.sh} 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.
@end quotation

At this moment there is no full implementation of path syncronization
process inside @command{centos-art.sh} script except by ``texinfo''
backend of help functionality which provides a restricted
implementation of path syncronization to this specific area of
documentation through the @option{--copy}, @option{--delete} and
@option{--rename} 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).

A practical example, through which you can notice the usefulness of
path syncronization process, is what happen when documentation entries
are renamed (@pxref{Directories trunk Scripts Functions Help}, for
more information).

@subheading Extending repository organization
@cindex Extending repository organization

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: What is the right place to store it?

The best place to find answers is in The CentOS Community (see page
@url{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.

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.

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
@file{trunk/Identity/Images/Themes} directory stores theme artistic
motifs, the @file{trunk/Identity/Models/Themes} directory stores theme
design models, the trunk/Manuals directory stores documentation files,
the @file{trunk/Locales} stores translation messages, and the
@file{trunk/Scripts} stores automation scripts.

To better illustrate this desition process, you can consider to examin
the @file{trunk/Identity/Images/Themes/TreeFlower/3} directory
structure as example. This directory can be read as: the theme
development line of version ``3'' of ``TreeFlower'' artistic motif.
Additional, we can say that ``TreeFlower'' artistic motif is part of
themes, as themes are part of The CentOS Project corporate visual
identity.

The relationship between conceptual ideas can be stablished by reading
each repository documentation entry individually, from trunk directory
to a deeper directory in the path. For reading repository
documentation entries we use the @code{help} functionality of
@command{centos-art.sh} script (@pxref{Directories trunk Scripts
Functions Help}).

@subheading File names convenction
@cindex File names convenction

Inside the CentOS Artwork Repository, generally, file names are all
written in lowercase (e.g., @file{01-welcome.png}, @file{splash.png},
@file{anaconda_header.png}, etc.) and directory names are all written
capitalized (e.g., @file{Identity}, @file{Themes}, @file{Motifs}) and
sometimes in cammel case (e.g., @file{TreeFlower}, etc.).

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.

@subheading Layout
@cindex Layout

The CentOS Artwork Repository is organized through a convenctional
``trunk'', ``branches'' and ``tags'' layout. For a complete reference
of each directory inside the repository @pxref{Directories}.