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