docs/dev/repository.txt

   1 =====================================
   2  The Docutils_ Subversion Repository
   3 =====================================
   4
   5 :Author: Lea Wiemann
   6 :Contact: LeWiemann@gmail.com
   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.berlios.de/svnroot/repos/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 ``svn.berlios.de``.
  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 Note that while the repository and the snapshots reside at BerliOS_,
  34 all other project data (web site, releases, mailing lists, trackers)
  35 is hosted by SourceForge.net_.
  36
  37 For the project policy on repository use (check-in requirements,
  38 branching, etc.), please see the `Docutils Project Policies`__.
  39
  40 __ policies.html#subversion-repository
  41
  42 .. _Subversion: http://subversion.tigris.org/
  43 .. _Subversion Book: http://svnbook.red-bean.com/
  44 .. _TortoiseSVN: http://tortoisesvn.tigris.org/
  45 .. _BerliOS: http://developer.berlios.de/
  46 .. _SourceForge.net: http://sourceforge.net/
  47
  48 .. contents::
  49
  50
  51 Accessing the Repository
  52 ========================
  53
  54 General Information
  55 -------------------
  56
  57 Web Access
  58 ~~~~~~~~~~
  59
  60 The repository can be browsed and examined via the web at
  61 http://svn.berlios.de/viewcvs/docutils/.
  62
  63
  64 Repository Access Methods
  65 ~~~~~~~~~~~~~~~~~~~~~~~~~
  66
  67 To get a checkout of the Docutils repository, first determine the root
  68 of the repository depending on your preferred protocol::
  69
  70     svn://svn.berlios.de/docutils                     (anonymous)
  71     http://svn.berlios.de/svnroot/repos/docutils      (anonymous + developers)
  72     https://svn.berlios.de/svnroot/repos/docutils     (anonymous + developers)
  73     svn+ssh://<username>@svn.berlios.de/svnroot/repos/docutils
  74                                                       (developers only)
  75
  76
  77 Checking Out the Repository
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 To check out only the current main source tree of Docutils, type ::
  81
  82     svn checkout ROOT/trunk/docutils
  83
  84 (Substitute your preferred repository root for ROOT.)  To check out
  85 everything (main tree, sandboxes, web site, and parallel projects),
  86 type ::
  87
  88     svn checkout ROOT/trunk docutils
  89
  90 This will create a working copy of the whole trunk in a new directory
  91 called ``docutils``.
  92
  93 Note that you probably do *not* want to check out the ROOT itself
  94 (without "/trunk"), because then you'd end up fetching the whole
  95 Docutils tree for every branch and tag over and over again.
  96
  97 To update your working copy later on, ``cd`` into the working copy and
  98 type ::
  99
 100     svn update
 101
 102
 103 Switching the Repository Root
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105
 106 If you changed your mind and want to use a different repository root,
 107 ``cd`` into your working copy and type::
 108
 109     svn switch --relocate OLDROOT NEWROOT
 110
 111
 112 Information for Developers
 113 --------------------------
 114
 115 If you would like to have write access to the repository, register
 116 with SourceForge.net_ and BerliOS_, and send your SourceForge.net and
 117 BerliOS user names to docutils-develop@lists.sourceforge.net.
 118 (Note that there may be a delay of several hours until you can commit
 119 changes to the repository.)
 120
 121
 122 Setting Up Your Subversion Client For Development
 123 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 124
 125 Before commiting changes to the repository, please ensure that the
 126 following lines are contained (and uncommented) in your local
 127 ~/.subversion/config file, so that new files are added with the
 128 correct properties set::
 129
 130     [miscellany]
 131     # For your convenience:
 132     global-ignores = ... *.pyc ...
 133     # For correct properties:
 134     enable-auto-props = yes
 135
 136     [auto-props]
 137     *.py = svn:eol-style=native;svn:keywords=Author Date Id Revision
 138     *.txt = svn:eol-style=native;svn:keywords=Author Date Id Revision
 139     *.html = svn:eol-style=native;svn:keywords=Author Date Id Revision
 140     *.xml = svn:eol-style=native;svn:keywords=Author Date Id Revision
 141     *.tex = svn:eol-style=native;svn:keywords=Author Date Id Revision
 142     *.css = svn:eol-style=native;svn:keywords=Author Date Id Revision
 143     *.patch = svn:eol-style=native
 144     *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Id Revision
 145     *.png = svn:mime-type=image/png
 146     *.jpg = svn:mime-type=image/jpeg
 147     *.gif = svn:mime-type=image/gif
 148
 149
 150 Setting Up SSH Keys
 151 ~~~~~~~~~~~~~~~~~~~
 152
 153 If you are a developer and you are using the svn+ssh access method
 154 instead of https or http, you may want to set a public & private key
 155 pair, so that you can access the shell and Subversion servers without
 156 having to enter your password.
 157
 158 To do this, log in on BerliOS_ and copy and paste your SSH public key
 159 into the edit box on the "`CVS/SVN/SSH Shared Keys`__" page.  Further
 160 instructions are available on this page.
 161
 162 __ https://developer.berlios.de/account/editsshkeys.php
 163
 164
 165 Migration from SourceForge.net
 166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 167
 168 Developers who had write-access for Docutils' CVS repository on
 169 SourceForge.net should `register with BerliOS`__ and send a message
 170 with their BerliOS user name to docutils-develop@lists.sourceforge.net.
 171
 172 __ https://developer.berlios.de/account/register.php
 173
 174
 175 Repository Layout
 176 =================
 177
 178 The following tree shows the repository layout::
 179
 180     docutils/
 181     |-- branches/
 182     |   |-- branch1/
 183     |   |   |-- docutils/
 184     |   |   |-- sandbox/
 185     |   |   `-- web/
 186     |   `-- branch2/
 187     |       |-- docutils/
 188     |       |-- sandbox/
 189     |       `-- web/
 190     |-- tags/
 191     |   |-- tag1/
 192     |   |   |-- docutils/
 193     |   |   |-- sandbox/
 194     |   |   `-- web/
 195     |   `-- tag2/
 196     |       |-- docutils/
 197     |       |-- sandbox/
 198     |       `-- web/
 199     `-- trunk/
 200         |-- docutils/
 201         |-- sandbox/
 202         `-- web/
 203
 204 The main source tree lives at ``docutils/trunk/docutils/``, next to
 205 the sandboxes (``docutils/trunk/sandbox/``) and the web site files
 206 (``docutils/trunk/web/``).
 207
 208 ``docutils/branches/`` and ``docutils/tags/`` contain (shallow) copies
 209 of either the whole trunk or only the main source tree
 210 (``docutils/trunk/docutils``).