Blame Manuals/Repository/en_US/Introduction/repo-convenctions.texinfo

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