<chapter id="intro-usage" xreflabel="Usage convenctions"> <title>Repository 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</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 Directories part.</para> </sect1> </chapter>