docs/dev/repository.txt

   1 =====================================
   2  The Docutils_ Subversion Repository
   3 =====================================
   4
   5 :Author: Lea Wiemann
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. _Docutils: http://docutils.sourceforge.net/
  12
  13 .. admonition:: Quick Instructions
  14
  15    To get a checkout of the Docutils source tree (without the
  16    sandboxes), type ::
  17
  18        svn checkout http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils
  19
  20    If you are going to commit changes to the repository, please read
  21    the **whole document**, especially the section "`Information for
  22    Developers`_"!
  23
  24 Docutils uses a Subversion_ repository located at ``docutils.svn.sourceforge.net``.
  25 Subversion is exhaustively documented in the `Subversion Book`_
  26 (svnbook).
  27
  28 While Unix and Mac OS X users will probably prefer the standard
  29 Subversion command line interface, Windows user may want to try
  30 TortoiseSVN_, a convenient explorer extension.  The instructions apply
  31 analogously.
  32
  33 For the project policy on repository use (check-in requirements,
  34 branching, etc.), please see the `Docutils Project Policies`__.
  35
  36 __ policies.html#subversion-repository
  37
  38 .. _Subversion: http://subversion.tigris.org/
  39 .. _Subversion Book: http://svnbook.red-bean.com/
  40 .. _TortoiseSVN: http://tortoisesvn.tigris.org/
  41 .. _SourceForge.net: http://sourceforge.net/
  42
  43 .. contents::
  44
  45
  46 Accessing the Repository
  47 ========================
  48
  49 General Information
  50 -------------------
  51
  52 Web Access
  53 ~~~~~~~~~~
  54
  55 The repository can be browsed and examined via the web at
  56 http://docutils.svn.sourceforge.net/viewvc/docutils/.
  57
  58
  59 Repository Access Methods
  60 ~~~~~~~~~~~~~~~~~~~~~~~~~
  61
  62 To get a checkout of the Docutils repository, first determine the root
  63 of the repository depending on your preferred protocol::
  64
  65     https://docutils.svn.sourceforge.net/svnroot/docutils (anonymous)
  66     https://<username>@docutils.svn.sourceforge.net/svnroot/docutils
  67                                                     (developers only)
  68
  69 Checking Out the Repository
  70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  71
  72 To check out only the current main source tree of Docutils, type ::
  73
  74     svn checkout ROOT/trunk/docutils
  75
  76 (Substitute your preferred repository root for ROOT.)  To check out
  77 everything (main tree, sandboxes, web site, and parallel projects),
  78 type ::
  79
  80     svn checkout ROOT/trunk docutils
  81
  82 This will create a working copy of the whole trunk in a new directory
  83 called ``docutils``.
  84
  85 Note that you probably do *not* want to check out the ROOT itself
  86 (without "/trunk"), because then you'd end up fetching the whole
  87 Docutils tree for every branch and tag over and over again.
  88
  89 To update your working copy later on, ``cd`` into the working copy and
  90 type ::
  91
  92     svn update
  93
  94
  95 Switching the Repository Root
  96 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  97
  98 If you changed your mind and want to use a different repository root,
  99 ``cd`` into your working copy and type::
 100
 101     svn switch --relocate OLDROOT NEWROOT
 102
 103
 104 Information for Developers
 105 --------------------------
 106
 107 If you would like to have write access to the repository, register
 108 with SourceForge.net_ and send your SourceForge.net
 109 user names to docutils-develop@lists.sourceforge.net.
 110 (Note that there may be a delay of several hours until you can commit
 111 changes to the repository.)
 112
 113 Sourceforge subversion access is documented `here`__
 114
 115 __ http://sourceforge.net/apps/trac/sourceforge/wiki/Subversion
 116
 117
 118 Setting Up Your Subversion Client For Development
 119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 120
 121 Before commiting changes to the repository, please ensure that the
 122 following lines are contained (and uncommented) in your local
 123 ~/.subversion/config file, so that new files are added with the
 124 correct properties set::
 125
 126     [miscellany]
 127     # For your convenience:
 128     global-ignores = ... *.pyc ...
 129     # For correct properties:
 130     enable-auto-props = yes
 131
 132     [auto-props]
 133     *.py = svn:eol-style=native;svn:keywords=Author Date Id Revision
 134     *.txt = svn:eol-style=native;svn:keywords=Author Date Id Revision
 135     *.html = svn:eol-style=native;svn:keywords=Author Date Id Revision
 136     *.xml = svn:eol-style=native;svn:keywords=Author Date Id Revision
 137     *.tex = svn:eol-style=native;svn:keywords=Author Date Id Revision
 138     *.css = svn:eol-style=native;svn:keywords=Author Date Id Revision
 139     *.patch = svn:eol-style=native
 140     *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Id Revision
 141     *.png = svn:mime-type=image/png
 142     *.jpg = svn:mime-type=image/jpeg
 143     *.gif = svn:mime-type=image/gif
 144
 145
 146 Repository Layout
 147 =================
 148
 149 The following tree shows the repository layout::
 150
 151     docutils/
 152     |-- branches/
 153     |   |-- branch1/
 154     |   |   |-- docutils/
 155     |   |   |-- sandbox/
 156     |   |   `-- web/
 157     |   `-- branch2/
 158     |       |-- docutils/
 159     |       |-- sandbox/
 160     |       `-- web/
 161     |-- tags/
 162     |   |-- tag1/
 163     |   |   |-- docutils/
 164     |   |   |-- sandbox/
 165     |   |   `-- web/
 166     |   `-- tag2/
 167     |       |-- docutils/
 168     |       |-- sandbox/
 169     |       `-- web/
 170     `-- trunk/
 171         |-- docutils/
 172         |-- sandbox/
 173         `-- web/
 174
 175 The main source tree lives at ``docutils/trunk/docutils/``, next to
 176 the sandboxes (``docutils/trunk/sandbox/``) and the web site files
 177 (``docutils/trunk/web/``).
 178
 179 ``docutils/branches/`` and ``docutils/tags/`` contain (shallow) copies
 180 of either the whole trunk or only the main source tree
 181 (``docutils/trunk/docutils``).