From d7166266eb565fdc094bac91c145f40b9818ee2a Mon Sep 17 00:00:00 2001 From: wiemann Date: Sun, 4 Mar 2007 19:23:22 +0000 Subject: reorganized, added and improved instructions git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4990 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/repository.txt | 210 +++++++++++++++++++++++------------------------- 1 file changed, 99 insertions(+), 111 deletions(-) diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt index d02ce6dbc..252dc0ba5 100644 --- a/docs/dev/repository.txt +++ b/docs/dev/repository.txt @@ -10,7 +10,16 @@ .. _Docutils: http://docutils.sourceforge.net/ -.. contents:: +.. admonition:: Quick Instructions + + To get a checkout of the Docutils source tree (without the + sandboxes), type :: + + svn co http://svn.berlios.de/svnroot/repos/docutils/trunk/docutils + + If you are going to commit changes to the repository, please read + the **whole document**, especially the section "`Information for + Developers`_"! Docutils uses a Subversion_ repository located at ``svn.berlios.de``. Subversion is exhaustively documented in the `Subversion Book`_ @@ -19,120 +28,94 @@ Subversion is exhaustively documented in the `Subversion Book`_ .. _Subversion: http://subversion.tigris.org/ .. _Subversion Book: http://svnbook.red-bean.com/ -.. Note:: +Note that while the repository and the snapshots reside at BerliOS_, +all other project data (web site, releases, mailing lists, trackers) +is hosted by SourceForge.net_. - While the repository resides at BerliOS, all other project data - (web site, snapshots, releases, mailing lists, trackers) is hosted - at SourceForge. +.. _BerliOS: http://developer.berlios.de/ +.. _SourceForge.net: http://sourceforge.net/ For the project policy on repository use (check-in requirements, branching, etc.), please see the `Docutils Project Policies`__. __ policies.html#subversion-repository +.. contents:: + Accessing the Repository ======================== +General Information +------------------- + Web Access ----------- +~~~~~~~~~~ The repository can be browsed and examined via the web at http://svn.berlios.de/viewcvs/docutils/. -Anonymous Access ----------------- - -Anonymous (read-only) access is available at ``svn://svn.berlios.de/docutils/``. - -To check out the current main source tree of Docutils, type :: +Repository Access Methods +~~~~~~~~~~~~~~~~~~~~~~~~~ - svn checkout svn://svn.berlios.de/docutils/trunk/docutils +To get a checkout of the Docutils repository, first determine the root +of the repository depending on your preferred protocol:: -To check out everything (main tree, sandboxes, and web site), type :: + svn://svn.berlios.de/docutils (anonymous) + http://svn.berlios.de/svnroot/repos/docutils (anonymous + developers) + https://svn.berlios.de/svnroot/repos/docutils (anonymous + developers) + svn+ssh://@svn.berlios.de/svnroot/repos/docutils + (developers only) - svn checkout svn://svn.berlios.de/docutils/trunk docutils -This will create a working copy of the whole trunk in a new directory -called ``docutils``. +Checking Out the Repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you cannot use the ``svn`` port, you can also use the HTTP access -method by substituting "http://svn.berlios.de/svnroot/repos" for -"svn://svn.berlios.de". +To check out only the current main source tree of Docutils, type :: -Note that you should *not* check out ``svn://svn.berlios.de/docutils`` -(without "trunk"), because then you'd end up fetching the whole -Docutils tree for every branch and tag over and over again, wasting -your and BerliOS's bandwidth. + svn checkout ROOT/trunk/docutils -To update your working copy later on, cd into the working copy and +(Substitute your preferred repository root for ROOT.) To check out +everything (main tree, sandboxes, web site, and parallel projects), type :: - svn update - - -Workaround for Localized Dates ------------------------------- - -If you have a non-english locale, you should perform all check-out and update -operations with ``LC_TIME=C`` in the environment. Either set it in your shell -init file, or (if you like localized dates in other programs) always do :: - - env LC_TIME=C svn checkout ... - env LC_TIME=C svn update ... - -This applies both to anonymous and developer access. - -The reason is that subversion localizes its expansion of the ``Date`` -keyword, which may result in non-ASCII characters in other locales. -Non-ASCII characters upset Python, even if they only appear in comments. -Strangely, Subversion always uses UTF-8 to format the date, ignoring -locale settings. So adding a UTF-8 encoding declaration to all Python -sources would help. However, we are not sure we want to do this. - -Arguably, the Right Thing would be for subversion to understand file -encodings: convert file contents, localize keywords and expand an Encoding -keyword to reflect the encoding used. But for now, ``LC_TIME=C`` fixes this -by disabling the translation of the date (the current time zone is still -respected). + svn checkout ROOT/trunk docutils +This will create a working copy of the whole trunk in a new directory +called ``docutils``. -Developer Access ----------------- +Note that you probably do *not* want to check out the ROOT itself +(without "/trunk"), because then you'd end up fetching the whole +Docutils tree for every branch and tag over and over again. -(Developers who had write-access for Docutils' CVS repository on -SourceForge.net should `register at BerliOS`__ and send a message with -their BerliOS user name to `Felix Wiemann `_.) +To update your working copy later on, ``cd`` into the working copy and +type :: -__ https://developer.berlios.de/account/register.php + svn update -If you are a developer, you get read-write access via -``svn+ssh://@svn.berlios.de/svnroot/repos/docutils/``, where -```` is your BerliOS user account name. So to retrieve a -working copy, type :: - svn checkout svn+ssh://@svn.berlios.de/svnroot/repos/docutils/trunk \ - docutils +Switching the Repository Root +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you have a non-english locale, set ``LC_TIME=C`` as described above. +If you changed your mind and want to use a different repository root, +``cd`` into your working copy and type:: -If you previously had an anonymous working copy and gained developer -access, you can switch the URL associated with your working copy with -this command (executed in the root of your working copy) :: + svn switch --relocate OLDROOT NEWROOT - svn switch --relocate svn://svn.berlios.de/docutils \ - svn+ssh://@svn.berlios.de/svnroot/repos/docutils -(Again, ```` is your BerliOS user account name.) +Information for Developers +-------------------------- -If you cannot use the ``ssh`` port, you can also use the HTTPS access -method by substituting "https://svn.berlios.de" for -"svn+ssh://svn.berlios.de". +If you would like to have write access to the repository, register +with SourceForge.net_ and BerliOS_, and send your SourceForge.net and +BerliOS user names to `Felix Wiemann `_. +(Note that there may be a delay of several hours until you can commit +changes to the repository.) Setting Up Your Subversion Client For Development -````````````````````````````````````````````````` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before commiting changes to the repository, please ensure that the following lines are contained (and uncommented) in your local @@ -159,53 +142,57 @@ correct properties set:: *.gif = svn:mime-type=image/gif -Setting Up SSH Access -````````````````````` - -With a public & private key pair, you can access the shell and -Subversion servers without having to enter your password. There are -two places to add your SSH public key on BerliOS: your web account and -your shell account. - -* Adding your SSH key to your BerliOS web account: +Workaround for Localized Dates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 1. Log in on the web at https://developer.berlios.de/. Create your - account first if necessary. You should be taken to your "My - Personal Page" (https://developer.berlios.de/my/). +If you have a non-english locale, you should perform all check-out and +update operations with ``LC_TIME=C`` in the environment. Either set +it in your shell init file (e.g. ``~/.bashrc``), or (if you like +localized dates in other programs) always do :: - 2. Choose "Account Options" from the menu below the top banner. + env LC_TIME=C svn checkout ... + env LC_TIME=C svn update ... - 3. At the bottom of the "Account Maintenance" page - (https://developer.berlios.de/account/) you'll find a "Shell - Account Information" section; click on "[Edit Keys]". +This applies both to anonymous and developer access. - 4. Copy and paste your SSH public key into the edit box on this page - (https://developer.berlios.de/account/editsshkeys.php). Further - instructions are available on this page. +The reason is that subversion localizes its expansion of the ``Date`` +keyword, which may result in non-ASCII characters in other locales. +Non-ASCII characters upset Python, even if they only appear in +comments. Strangely, Subversion always uses UTF-8 to format the date, +ignoring locale settings. So adding a UTF-8 encoding declaration to +all Python sources would help. However, we are not sure if we want to +do this. -* Adding your SSH key to your BerliOS shell account: +(Arguably, the Right Thing would be for subversion to understand file +encodings: convert file contents, localize keywords and expand an +Encoding keyword to reflect the encoding used. But for now, +``LC_TIME=C`` fixes this by disabling the translation of the date [the +current time zone is still respected].) - 1. Log in to the BerliOS shell server:: - ssh @shell.berlios.de +Setting Up SSH Keys +~~~~~~~~~~~~~~~~~~~ - You'll be asked for your password, which you set when you created - your account. +If you are a developer and you are using the svn+ssh access method +instead of https or http, you may want to set a public & private key +pair, so that you can access the shell and Subversion servers without +having to enter your password. - 2. Create a .ssh directory in your home directory, and remove - permissions for group & other:: +To do this, log in on BerliOS_ and copy and paste your SSH public key +into the edit box on the "`CVS/SVN/SSH Shared Keys`__" page. Further +instructions are available on this page. - mkdir .ssh - chmod og-rwx .ssh +__ https://developer.berlios.de/account/editsshkeys.php - Exit the SSH session. - 3. Copy your public key to the .ssh directory on BerliOS:: +Migration from SourceForge.net +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - scp .ssh/id_dsa.pub @shell.berlios.de:.ssh/authorized_keys +Developers who had write-access for Docutils' CVS repository on +SourceForge.net should `register with BerliOS`__ and send a message +with their BerliOS user name to `Felix Wiemann`_. - Now you should be able to start an SSH session without needing your - password. +__ https://developer.berlios.de/account/register.php Repository Layout @@ -237,9 +224,10 @@ The following tree shows the repository layout:: |-- sandbox/ `-- web/ -``docutils/branches/`` and ``docutils/tags/`` contain (shallow) copies -of the whole trunk. - The main source tree lives at ``docutils/trunk/docutils/``, next to the sandboxes (``docutils/trunk/sandbox/``) and the web site files (``docutils/trunk/web/``). + +``docutils/branches/`` and ``docutils/tags/`` contain (shallow) copies +of either the whole trunk or only the main source tree +(``docutils/trunk/docutils``). -- cgit v1.2.1