Blame Manuals/Repository/Docbook/Introduction/usage.docbook

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