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