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