Repository
ContentsBRTableOfContents |
About The Repository
The documentation sources for the project reside in Subversion, a revision management system. The Subversion repository is the hub of the core document development effort. Subversion helps us to work on the same files simultaneously without “clobbering” each others work. Any author wanting to contribute to the documentation effort can checkout their own a “Working Copy” (WC) of the documentation sources and make changes to this copy.
To checkout your working copy you will need to install subversion, most distros ship Subversion. If you have never worked with a version control system, don't be nervous - you cannot break anything in the repository, only your local, working copy. This is because you will be working as an anonymous user and therefore do not have the permissions to change anything in the repository. Only people with comitter permissions can make changes to the repository. People are given comitter status once they have consistently provided contributions and demonstrated commitment.
The good news is that Subversion is very well supported. As a result there are many resources available for learning. The most recommended resource is, the most excellent book, “Version Control with Subversion” http://svnbook.red-bean.com/.
This book is suited for the Subversion user and administrator, however it is a Command Line Interface (CLI) explanation of the Subversion features and functionality. Many people may prefer to use a GUI application instead of the CLI. There are a number of GUI front-ends to Subversion. Here is a list of some tools you may try:
- eSvn
- Rapid SVN
- TortoiseSVN
- Java SVN (JSVN)
Get the Repository
First thing: install the package called 'subversion' using your favourite package manager.
Now, if you type svn help you get some help about subversion's commands:
$ svn help usage: svn <subcommand> [options] [args] Type "svn help <subcommand>" for help on a specific subcommand. Most subcommands take file and/or directory arguments, recursing on the directories. If no arguments are supplied to such a command, it will recurse on the current directory (inclusive) by default. Available subcommands: add [...]
Then decide where you want to have your working copy of the source. In this guide, we assume you want it in the directory "ubuntu-doc" inside your home directory. Don't create the directory: subversion will do it by itself.
Then, get a copy of the repository (this is called checkout)
Change to your home directory.
cd ~
Perform the svn checkout.
svn checkout https://docteam.ubuntu.com/repos/trunk ubuntu-doc
This creates a directory ~/ubuntu-doc (change the name if you like) that contains a copy of the latest development version. It will ask for certificate informations (it's an HTTPS connection), which you can accept according to how you usually manage HTTPS certificates.
The first checkout takes a while, as it will download the full contents of the development versions. The good news is that once you have them, and you want to get a future (or past) version, subversion will not download the full contents, but only the changes.
Have a look around the repository. DocteamRepository contains a description of the various directories that you see. If you see some directory called .svn, those are used by subversion and should be left alone.
Now you have everything inside the ubuntu-doc directory, and you can work as you please. Don't worry if you break something: whatever you do, you can't break the repository on the server.
Authenticated Access
A number of the documentation team members have write access to the repository. They have the ability to merge changes made in their Working Copy directly into the repository. These people have been given a username and a password that enables them with read and write privileges to the repository.
Commiters do their first checkout in the same way described above. However, when doing their first commit (svn commit), they are prompted for a username and password.
This only needs to be done on the first commit, the 'username' and 'password' will be saved in the '.subversion' folder in their 'home' directory and used for all successive commit operations.
Repository Structure
The following is an explanation of the repository structure for the Ubuntu Documentation Project.
As per standard Subversion repository management the repository is arranged into three directories:
- trunk/
- branches/
- tags/
The trunk directory is where development happens for the current release. This is the working directory, and to begin with, you only need to download this directory. The branches directory is a place were people can make a fork from a revision in the trunk directory and work outside the main development stream. Why would anyone want to this? Well sometimes you want to make changes that are very large.
These changes would be intrusive to other developers, so you develop in a branch were your changes will not bother others. A branch can be merged back into trunk when the intrusive work is finished and changes in trunk can be merged into a branch at any time. The problem with branching is that, over time, the branch and the trunk can grow further apart. The more this happens the harder it becomes to merge the branch back into the trunk. It is therefore good practice to monitor trunk when working in a branch and to merge patches to trunk into the branch when possible. Other developers can also read and write to a branch. A more detailed explanation of how to mange branches can be found in the book “Revision Control with Subversion” http://svnbook.red-bean.com/ .
The tags directory is used to keep a specific revision of the documentation. Tagging normally coincides with a release so the tag is named by the release. For example:
Changes to a tag should never be required so, once a revision is tagged it is preserved for posterity. No one expect a repository administrator can make any changes and even then this should only be in rare circumstances. See that tags directory as a permanent archive. Things go in and are preserved there, in space and time, until the project is no more.
Other miscellaneous tips
If someone makes a change in the repository and you want your repository to be up-to-date, you can go inside the ubuntu-doc directory and type:
svn up
That will bring your repository up to date, and it's very quick.
Also, locally, subversion is able to revert (using svn revert <filename>) any file to how it was at the time of the last checkout or update.