Blame Identity/Manual/repository-html/repository_2.67.html

728c6d
728c6d
<html>
728c6d
728c6d
organization, and administration of CentOS Artwork Repository.
728c6d
728c6d
Copyright C 2009-2011 Alain Reguera Delgado
728c6d
728c6d
Permission is granted to copy, distribute and/or modify this document
728c6d
under the terms of the GNU Free Documentation License, Version 1.2 or
728c6d
any later version published by the Free Software Foundation; with no
728c6d
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
728c6d
copy of the license is included in the section entitled GNU Free
728c6d
Documentation License.  
728c6d
-->
728c6d
728c6d
728c6d
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
728c6d
            Karl Berry  <karl@freefriends.org>
728c6d
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
728c6d
            and many others.
728c6d
Maintained by: Many creative people <dev@texi2html.cvshome.org>
728c6d
Send bugs and suggestions to <users@texi2html.cvshome.org>
728c6d
728c6d
-->
728c6d
<head>
728c6d
<title>CentOS Artwork Repository: 2.67 The trunk/Scripts/Functions/Path Directory</title>
728c6d
728c6d
<meta name="description" content="CentOS Artwork Repository: 2.67 The trunk/Scripts/Functions/Path Directory">
728c6d
<meta name="keywords" content="CentOS Artwork Repository: 2.67 The trunk/Scripts/Functions/Path Directory">
728c6d
<meta name="resource-type" content="document">
728c6d
<meta name="distribution" content="global">
728c6d
<meta name="Generator" content="texi2html 1.76">
728c6d
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
728c6d
<style type="text/css">
728c6d
728c6d
/* CSS
728c6d
 *
728c6d
 * repository.css -- This file provides visual style for repository
728c6d
 * documentation manual in HTML format, as output by Texi2html
728c6d
 * program.
728c6d
 *
728c6d
 * Copyright (C) 2009-2011 Alain Reguera Delgado
728c6d
 *
728c6d
 * This program is free software; you can redistribute it and/or
728c6d
 * modify it under the terms of the GNU General Public License as
728c6d
 * published by the Free Software Foundation; either version 2 of the
728c6d
 * License, or (at your option) any later version.
728c6d
 * 
728c6d
 * This program is distributed in the hope that it will be useful, but
728c6d
 * WITHOUT ANY WARRANTY; without even the implied warranty of
728c6d
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
728c6d
 * General Public License for more details.
728c6d
 *
728c6d
 * You should have received a copy of the GNU General Public License
728c6d
 * along with this program; if not, write to the Free Software
728c6d
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
728c6d
 * USA.
728c6d
 * ----------------------------------------------------------------------
728c6d
 * $Id$
728c6d
 * ----------------------------------------------------------------------
728c6d
 */
728c6d
728c6d
@import url("/home/centos/artwork/trunk/Identity/Webenv/Css/base.css");
728c6d
@import url("/home/centos/artwork/trunk/Identity/Webenv/Css/base-app.css");
728c6d
728c6d
a.summary-letter {text-decoration: none}
728c6d
pre.display {font-family: serif}
728c6d
pre.format {font-family: serif}
728c6d
pre.menu-comment {font-family: serif}
728c6d
pre.menu-preformatted {font-family: serif}
728c6d
pre.smalldisplay {font-family: serif; font-size: smaller}
728c6d
pre.smallexample {font-size: smaller}
728c6d
pre.smallformat {font-family: serif; font-size: smaller}
728c6d
pre.smalllisp {font-size: smaller}
728c6d
span.sansserif {font-family:sans-serif; font-weight:normal;}
728c6d
ul.toc {list-style: none}
728c6d
-->
728c6d
</style>
728c6d
728c6d
728c6d
</head>
728c6d
728c6d
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
728c6d
728c6d
728c6d
[ < ]
728c6d
[ > ]
728c6d
   
728c6d
[Contents]
728c6d
[Index]
728c6d
[ ? ]
728c6d
728c6d
728c6d
728c6d

2.67 The <tt>`trunk/Scripts/Functions/Path'</tt> Directory

728c6d
    728c6d
    2.67.1 Goals 
    728c6d
    2.67.2 Description 
    728c6d
      728c6d
      2.67.2.1 Repository layout 
      728c6d
      2.67.2.2 Repository name convenctions 
      728c6d
      2.67.2.3 Repository work flow 
      728c6d
      2.67.2.4 Parallel directories 
      728c6d
      2.67.2.5 Syncronizing path information 
      728c6d
      2.67.2.6 What is the right place to store it? 
      728c6d
      728c6d
      2.67.3 Usage 
      728c6d
      2.67.4 See also 
      728c6d
      728c6d
      728c6d
      728c6d
      728c6d

      2.67.1 Goals

      728c6d
      728c6d

      This section exists to organize files related to path

      728c6d
      functiontionality.  The path functionality standardizes
      728c6d
      movement, syncronization, branching, tagging, and general file
      728c6d
      maintainance inside the repository. 
      728c6d

      728c6d
      728c6d
      728c6d

      2.67.2 Description

      728c6d
        728c6d
        2.67.2.1 Repository layout 
        728c6d
        2.67.2.2 Repository name convenctions 
        728c6d
        2.67.2.3 Repository work flow 
        728c6d
        2.67.2.4 Parallel directories 
        728c6d
        2.67.2.5 Syncronizing path information 
        728c6d
        2.67.2.6 What is the right place to store it? 
        728c6d
        728c6d
        728c6d

        "CentOS like trees, has roots, trunk, branches, leaves and

        728c6d
        flowers.  Day by day they work together in freedom, ruled by the laws
        728c6d
        of nature and open standards, to show the beauty of its existence."
        728c6d

        728c6d
        728c6d
        728c6d

        2.67.2.1 Repository layout

        728c6d
        728c6d

        The repository layout describes organization of files and directories

        728c6d
        inside the repository. The repository layout provides the standard
        728c6d
        backend required for automation scripts to work correctly. If such
        728c6d
        layout changes unexpectedly, automation scripts may confuse themselves
        728c6d
        and stop doing what we expect from them to do.
        728c6d

        728c6d

        As convenction, inside CentOS Artwork Repository, we organize files

        728c6d
        and directories related to CentOS corporate visual identity under
        728c6d
        three top level directories named: <tt>`trunk/'</tt>, <tt>`branches/'</tt>,
        728c6d
        and <tt>`tags/'</tt>. 
        728c6d

        728c6d

        The <tt>`trunk/'</tt> directory (see section The <tt>`trunk'</tt> Directory) organizes the main

        728c6d
        development line of CentOS corporate visual identity. Inside
        728c6d
        <tt>`trunk/'</tt> directory structure, the CentOS corporate visual
        728c6d
        identity concepts are implemented using directories.  There is one
        728c6d
        directory level for each relevant concept inside the repository. The
        728c6d
        <tt>`trunk/'</tt> directory structure is mainly used to perform
        728c6d
        development tasks related to CentOS corporate visual identity.
        728c6d

        728c6d

        The <tt>`branches/'</tt> directory () oranizes

        728c6d
        parallel development lines to <tt>`trunk/'</tt> directory. The
        728c6d
        <tt>`branches/'</tt> directory is used to set points in time where
        728c6d
        develpment lines are devided one from another taking separte and
        728c6d
        idependent lives that share a common past from the point they were
        728c6d
        devided on. The <tt>`branches/'</tt> directory is mainly used to perform
        728c6d
        quality assurance tasks related to CentOS corporate visual identity.
        728c6d

        728c6d

        The <tt>`tags/'</tt> directory (see section The <tt>`tags'</tt> Directory) organizes parallel frozen

        728c6d
        lines to <tt>`branches/'</tt> directory.  The parallel frozen lines are
        728c6d
        immutable, nothing change inside them once they has been created.  The
        728c6d
        <tt>`tags/'</tt> directory is mainly used to publish final releases of
        728c6d
        CentOS corporate visual identity.
        728c6d

        728c6d

        The CentOS Artwork Repository layout is firmly grounded on a

        728c6d
        Subversion base.  Subversion (http://subversion.tigris.org) is a
        728c6d
        version control system, which allows you to keep old versions of files
        728c6d
        and directories (usually source code), keep a log of who, when, and
        728c6d
        why changes occurred, etc., like CVS, RCS or SCCS.  Subversion keeps a
        728c6d
        single copy of the master sources.  This copy  is called the source
        728c6d
        "repository"; it contains all the information to permit extracting
        728c6d
        previous versions of those files at any time.
        728c6d

        728c6d
        728c6d
        728c6d

        2.67.2.2 Repository name convenctions

        728c6d
        728c6d

        Repository name convenctions help us to maintain consistency of names

        728c6d
        inside the repository.
        728c6d

        728c6d

        Repository name convenctions are applied to files and directories

        728c6d
        inside the repository layout. As convenction, inside the repository
        728c6d
        layout, file names are all written in lowercase
        728c6d
        (<samp>`01-welcome.png'</samp>, <samp>`splash.png'</samp>, <samp>`anaconda_header.png'</samp>,
        728c6d
        etc.) and directory names are all written capitalized (e.g.,
        728c6d
        <samp>`Identity'</samp>, <samp>`Themes'</samp>, <samp>`Motifs'</samp>, <samp>`TreeFlower'</samp>,
        728c6d
        etc.).
        728c6d

        728c6d

        Repository name convenctions are implemented inside the

        728c6d
        cli_getRepoName function of <tt>`centos-art.sh'</tt> script. With
        728c6d
        cli_getRepoName function we reduce the amount of commands and
        728c6d
        convenctions to remember, concentrating them in just one single place
        728c6d
        to look for fixes and improvements.
        728c6d

        728c6d
        728c6d
        728c6d

        2.67.2.3 Repository work flow

        728c6d
        728c6d

        Repository work flow describes the steps and time intervals used to

        728c6d
        produce CentOS corporate visual identity inside CentOS Artwork
        728c6d
        Repository.  
        728c6d

        728c6d

        To illustrate repository work flow let's consider themes' development

        728c6d
        cycle. 
        728c6d

        728c6d

        Initially, we start working themes on their trunk development line

        728c6d
        (e.g., <tt>`trunk/Identity/Themes/Motifs/TreeFlower/'</tt>), here we
        728c6d
        organize information that cannot be produced automatically (i.e.,
        728c6d
        background images, concepts, color information, screenshots, etc.).
        728c6d

        728c6d

        Later, when theme trunk development line is considered "ready" for

        728c6d
        implementation (e.g.,  all required backgrounds have been designed),
        728c6d
        we create a branch for it (e.g.,
        728c6d
        <tt>`branches/Identity/Themes/Motifs/TreeFlower/1/'</tt>).  Once the
        728c6d
        branch has been created, we forget that branch and continue working
        728c6d
        the trunk development line while others (e.g., an artwork quality
        728c6d
        assurance team) test the new branch for tunning it up. 
        728c6d

        728c6d

        Once the branch has been tunned up, and considered "ready" for

        728c6d
        release, it is freezed under <tt>`tags/'</tt> directory (e.g.,
        728c6d
        <tt>`tags/Identity/Themes/Motifs/TreeFower/1.0/'</tt>) for packagers,
        728c6d
        webmasters, promoters, and anyone who needs images from that CentOS
        728c6d
        theme the tag was created for.
        728c6d

        728c6d

        Both branches and tags, inside CentOS Artwork Repository, use

        728c6d
        numerical values to identify themselves under the same location.
        728c6d
        Branches start at one (i.e., <samp>`1'</samp>) and increment one unit for each
        728c6d
        branch created from the same trunk development line.  Tags start at
        728c6d
        zero (i.e., <samp>`0'</samp>) and increment one unit for each tag created from
        728c6d
        the same branch development line.
        728c6d

        728c6d
        Convenction

        Convenction

        Do not freeze trunk development lines using tags

        728c6d
        directly.  If you think you need to freeze a trunk development line,
        728c6d
        create a branch for it and then freeze that branch instead.
        728c6d

        728c6d
        728c6d

        The trunk development line may introduce problems we cannot see

        728c6d
        immediatly. Certainly, the high changable nature of trunk development
        728c6d
        line complicates finding and fixing such problems. On the other hand,
        728c6d
        the branched development lines provide a more predictable area where
        728c6d
        only fixes/corrections to current content are commited up to
        728c6d
        repository. 
        728c6d

        728c6d

        If others find and fix bugs inside the branched development line, we

        728c6d
        could merge such changes/experiences back to trunk development line
        728c6d
        (not visversa) in order for future branches, created from trunk, to
        728c6d
        benefit.
        728c6d

        728c6d

        Time intervals used to create branches and tags may vary, just as

        728c6d
        different needs may arrive. For example, consider the release schema
        728c6d
        of CentOS distribution: one major release every 2 years, security
        728c6d
        updates every 6 months, support for 7 years long. Each time a CentOS
        728c6d
        distribution is released, specially if it is a major release, there is
        728c6d
        a theme need in order to cover CentOS distribution artwork
        728c6d
        requirements. At this point, is where CentOS Artwork Repository comes
        728c6d
        up to scene. 
        728c6d

        728c6d

        Before releasing a new major release of CentOS distribution we create

        728c6d
        a branch for one of several theme development lines available inside
        728c6d
        the CentOS Artwork Repository, perform quality assurance on it, and
        728c6d
        later, freeze that branch using tags. Once a the theme branch has been
        728c6d
        frozen (under <tt>`tags/'</tt> directory), CentOS Packagers (the persons
        728c6d
        whom build CentOS distribution) can use that frozen branch as source
        728c6d
        location to fulfill CentOS distribution artwork needs. The same
        728c6d
        applies to CentOS Webmasters (the persons whom build CentOS websites),
        728c6d
        and any other visual manifestation required by the project.
        728c6d

        728c6d
        728c6d
        728c6d

        2.67.2.4 Parallel directories

        728c6d
        728c6d

        Inside CentOS Artwork Repository, parallel directories are simple

        728c6d
        directory entries built from a common parent directory and placed in a
        728c6d
        location different to that, the common parent directory is placed on.
        728c6d
        Parallel directories are useful to create branches, tags,
        728c6d
        translations, documentation, pre-rendering configuration script, and
        728c6d
        similar directory structures.
        728c6d

        728c6d

        Parallel directories take their structure from one unique parent

        728c6d
        directory. Inside CentOS Artwork Repository, this unique parent
        728c6d
        directory is under <tt>`trunk/Identity'</tt> location.  The
        728c6d
        <tt>`trunk/Identity'</tt> location must be considered the reference for
        728c6d
        whatever information you plan to create inside the repository.
        728c6d

        728c6d

        In some circumstances, parallel directories may be created removing

        728c6d
        uncommon information from their paths. Uncommon path information
        728c6d
        refers to those directory levels in the path which are not common for
        728c6d
        other parallel directories.  For example, when rendering
        728c6d
        <tt>`trunk/Identity/Themes/Motifs/TreeFlower/Distro'</tt> directory
        728c6d
        structure, the <tt>`centos-art.sh'</tt> script removes the
        728c6d
        <tt>`Motifs/TreeFlower/'</tt> directory levels from path, in order to
        728c6d
        build the parallel directory used to retrived translations, and
        728c6d
        pre-rendering configuration scripts required by render
        728c6d
        functionality.
        728c6d

        728c6d

        Another example of parallel directory is the documentation structure

        728c6d
        created by manual functionality. This time,
        728c6d
        <tt>`centos-art.sh'</tt> script uses parallel directory information with
        728c6d
        uncommon directory levels to build the documentation entry required by
        728c6d
        Texinfo documentation system, inside the repository.
        728c6d

        728c6d

        Othertimes, parallel directories may add uncommon information to their

        728c6d
        paths. This is the case we use to create branches and tags. When we
        728c6d
        create branches and tags, a numerical identifier is added to parallel
        728c6d
        directory structure path. The place where the numerical identifier is
        728c6d
        set on is relevant to corporate visual identity structure and should
        728c6d
        be carefully considered where it will be.
        728c6d

        728c6d

        When one parent directory changes, all their related parallel

        728c6d
        directories need to be changed too. This is required in order for
        728c6d
        parallel directories to retain their relation with the parent
        728c6d
        directory structure.  In the other hand, parallel directories should
        728c6d
        never be modified under no reason but to satisfy the relation to their
        728c6d
        parent directory structure.  Liberal change of parallel directories
        728c6d
        may suppresses the conceptual idea they were initially created for;
        728c6d
        and certainly, things may stop working the way they should do.
        728c6d

        728c6d
        728c6d
        728c6d

        2.67.2.5 Syncronizing path information

        728c6d
        728c6d

        Parallel directories are very useful to keep repository organized but

        728c6d
        introduce some complications.  For instance, consider what would
        728c6d
        happen to functionalities like manual (<samp>`trunk Scripts Bash
        728c6d
        Functions Manual'</samp>) that rely on parent directory structures to create
        728c6d
        documentation entries (using parallel directory structures) if one of
        728c6d
        those parent directory structures suddenly changes after the
        728c6d
        documentation entry has been already created for it? 
        728c6d

        728c6d

        In such cases, functionalities like manual may confuse

        728c6d
        themselves if path information is not updated to reflect the relation
        728c6d
        with its parent directory.  Such functionalities work with parent
        728c6d
        directory structure as reference; if a parent directory changes, the
        728c6d
        functionalities dont't even note it because they work with the last
        728c6d
        parent directory structure available in the repository, no matter what
        728c6d
        it is. 
        728c6d

        728c6d

        In the specific case of documentation (the manual

        728c6d
        functionality), the problem mentioned above provokes that older parent
        728c6d
        directories, already documented, remain inside documentation directory
        728c6d
        structures as long as you get your hands into the documentation
        728c6d
        directory structure (<tt>`trunk/Manuals'</tt>) and change what must be
        728c6d
        changed to match the new parent directory structure.
        728c6d

        728c6d

        There is no immediate way for manual, and similar

        728c6d
        functionalities that use parent directories as reference, to know when
        728c6d
        and how directory movements take place inside the repository. Such
        728c6d
        information is available only when the file movement itself takes
        728c6d
        place inside the repository. So, is there, at the moment of moving
        728c6d
        files, when we need to syncronize parallel directories with their
        728c6d
        unique parent directory structure.
        728c6d

        728c6d
        Warning

        Warning

        There is not support for URL reference inside

        728c6d
        <tt>`centos-art.sh'</tt> script.  The <tt>`centos-art.sh'</tt> script is
        728c6d
        designed to work with local files inside the working copy only.
        728c6d

        728c6d
        728c6d

        As CentOS Artwork Repository is built over a version control system,

        728c6d
        file movements inside the repository are considered repository
        728c6d
        changes. In order for these repository changes to be versioned, we
        728c6d
        need to, firstly, add changes into the version control system, commit
        728c6d
        them, and later, perform movement actions using version control system
        728c6d
        commands. This configuration makes possible for everyone to know about
        728c6d
        changes details inside the repository; and if needed, revert or update
        728c6d
        them back to a previous revision.
        728c6d

        728c6d

        Finally, once all path information has been corrected, it is time to

        728c6d
        take care of information inside the files. For instance, considere
        728c6d
        what would happen if you make a reference to a documentation node, and
        728c6d
        later the documentation node you refere to is deleted. That would make
        728c6d
        Texinfo to produce error messages at export time. So, the
        728c6d
        <tt>`centos-art.sh'</tt> script needs to know when such changes happen, in
        728c6d
        a way they could be noted and handled without producing errors.
        728c6d

        728c6d
        728c6d
        728c6d

        2.67.2.6 What is the right place to store it?

        728c6d
        728c6d

        Occasionly, you may find that new corporate visual identity components

        728c6d
        need to be added to the repository. If that is your case, the first
        728c6d
        question you need to ask yourself, before start to create directories
        728c6d
        blindly all over, is: What is the right place to store it?
        728c6d

        728c6d

        The CentOS Community different free support vains (see:

        728c6d
        http://wiki.centos.org/GettingHelp) are the best place to find
        728c6d
        answers to your question, but going there with hands empty is not good
        728c6d
        idea. It may give the impression you don't really care about. Instead,
        728c6d
        consider the following suggestions to find your own comprehension and
        728c6d
        so, make your propositions based on it.
        728c6d

        728c6d

        When we are looking for the correct place to store new files, to bear

        728c6d
        in mind the corporate visual identity structure used inside the CentOS
        728c6d
        Artwork Repository (see section The <tt>`trunk/Identity'</tt> Directory) would be probaly the best
        728c6d
        advice we could offer, the rest is just matter of choosing appropriate
        728c6d
        names.  To illustrate this desition process let's consider the
        728c6d
        <tt>`trunk/Identity/Themes/Motifs/TreeFlower'</tt> directory as example.
        728c6d
        It is the trunk development line of TreeFlower artistic motif.
        728c6d
        Artistic motifs are considered part of themes, which in turn are
        728c6d
        considered part of CentOS corporate visual identity.
        728c6d

        728c6d

        When building parent directory structures, you may find that reaching

        728c6d
        an acceptable location may take some time, and as it uses to happen
        728c6d
        most of time; once you've find it, that may be not a definite
        728c6d
        solution.  There are many concepts that you need to play with, in
        728c6d
        order to find a result that match the conceptual idea you try to
        728c6d
        implement in the new directory location. To know which these concepts
        728c6d
        are, split the location in words and read its documentation entry from
        728c6d
        less specific to more specific.
        728c6d

        728c6d

        For example, the <tt>`trunk/Identity/Themes/Motifs/TreeFlower'</tt>

        728c6d
        location evolved through several months of contant work and there is
        728c6d
        no certain it won't change in the future, even it fixes quite well the
        728c6d
        concept we are trying to implement.  The concepts used in
        728c6d
        <tt>`trunk/Identity/Themes/Distro/Motifs/TreeFlower'</tt> location are
        728c6d
        described in the following commands, respectively:
        728c6d

        728c6d
        centos-art manual --read=turnk/
        728c6d
        centos-art manual --read=turnk/Identity/
        728c6d
        centos-art manual --read=turnk/Identity/Themes/
        728c6d
        centos-art manual --read=turnk/Identity/Themes/Motifs/
        728c6d
        centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/
        728c6d
        728c6d

        Other location concepts can be found similary as we did above, just

        728c6d
        change the location we used above by the one you are trying to know
        728c6d
        concepts for.
        728c6d

        728c6d
        728c6d
        728c6d

        2.67.3 Usage

        728c6d
        728c6d
        728c6d
        centos-art path --copy='SRC' --to='DST'
        728c6d
        728c6d

        Copy <samp>`SRC'</samp> to <samp>`DST'</samp> and schedule <samp>`DST'</samp> for

        728c6d
        addition (with history).  In this command, <tt>`SRC'</tt> and <tt>`DST'</tt>
        728c6d
        are both working copy (WC) entries.
        728c6d

        728c6d
        728c6d
        centos-art path --delete='SRC'
        728c6d
        728c6d

        Delete <samp>`DST'</samp>. In order for this command to work the file or

        728c6d
        directory you intend to delete should be under version control first.
        728c6d
        In this command, <tt>`SRC'</tt> is a working copy (WC) entry.  
        728c6d

        728c6d
        728c6d
        728c6d
        728c6d
        728c6d
        728c6d

        2.67.4 See also

        728c6d
        728c6d
        728c6d
        728c6d
        728c6d
        [Contents]
        728c6d
        [Index]
        728c6d
        [ ? ]
        728c6d
        728c6d

        728c6d
         <font size="-1">
        728c6d
          This document was generated on March, 30 2011 using texi2html 1.76.
        728c6d
         </font>
        728c6d
         
        728c6d
        728c6d

        728c6d
        </body>
        728c6d
        </html>