<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 

        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., render for producing images,

        help for manage documentation, and

        locale 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 

        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 

        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 

    class="directory">trunk/Identity/Models</filename> directory

    structure and the auxiliar paths under 

    class="directory">trunk/Identity/Images</filename>, 

    class="directory">trunk/Locales</filename> and 

    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

    class="directory">trunk/Identity/Models/Brands</filename>, we'll

    end up having, at least, the 

    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 

    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

    help 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>

    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 

        class="directory">trunk/Identity/Images/Themes</filename>

        directory stores theme artistic motifs, the 

        class="directory">trunk/Identity/Models/Themes</filename>

        directory stores theme design models, the 

        class="directory">trunk/Manuals</filename> directory stores

        documentation files, the 

        class="directory">trunk/Locales</filename> stores translation

        messages, and the 

        class="directory">trunk/Scripts</filename> stores automation

        scripts.</para>

        <para>To better illustrate this desition process, you can

        consider to examin the 

        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 

        class="directory">trunk</filename> directory to a deeper

        directory in the path. For reading repository documentation

        entries we use the help 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., 

        role="directory">Identity</filename>, 

        role="directory">Themes</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 Directories

        part.</para>

    </sect1>

</chapter>