Repository

Differences between revisions 18 and 19
Revision 18 as of 2011-05-26 21:17:29
Size: 7046
Editor: 85-210-11-2
Comment: add a couple of clarificatory sentences
Revision 19 as of 2014-01-22 00:05:50
Size: 3055
Editor: dsmythies
Comment: attempt to make this page a little less obsolete (not finished.)
Deletions are marked like this. Additions are marked like this.
Line 21: Line 21:
|| [[https://code.launchpad.net/~ubuntu-core-doc/gnome-user-docs|gnome-user-docs]] || Help for Gnome Shell ||
|| [[https://code.launchpad.net/~ubuntu-core-doc/kubuntu-docs|kubuntu-docs]] || Kubuntu desktop help ||
Line 24: Line 22:
|| [[https://code.launchpad.net/~ubuntu-core-doc/edubuntu-docs|edubuntu-docs]] || Edubuntu help ||
Line 26: Line 23:

''Note'': for natty the Ubuntu desktop help is found in the {{{gnome-user-docs}}} branch rather than the {{{ubuntu-docs}}} branch.
Line 31: Line 26:
== Installing Bazaar ==

In order to use Bazaar, install the {{{bzr}}} package.

Once installed, type {{{bzr whoami 'Your Name <you@example.com>'}}} in a Terminal to identify yourself to bzr. You might also need to change the bazaar plugin that manages launchpad login to match your launchpad username. {{{bzr launchpad-login <launchpad user name>}}} should change this.

== Generating SSH keys ==
If you are using bazaar over ssh, you might also need to generate ssh keys and add it to Launchpad.

 1. Type {{{ssh-keygen -t rsa}}} to generate a ssh key. If you already have generated ssh keys, feel free to ignore this step.
 2. Visit https://launchpad.net/people/+me/+editsshkeys and update your ssh keys.

See [[https://help.ubuntu.com/community/SSH/OpenSSH/Keys|OpenSSH Keys]] for more information about generating and using ssh keys.

== Getting the docs ==

To make changes to documentation held in a Bazaar branch, you first need to download a copy onto your computer.

The first step is to identify the particular Bazaar branch which you want to download. The Doc Team works with several different branches. A list is at the top of this page. Choose your branch, and follow these instructions.

 1. Open a Terminal by pressing '''Applications''' -> '''Accessories''' -> '''Terminal'''.
 1. Type {{{mkdir ubuntu_bzr}}} and press enter. This will create a new directory called ''ubuntu_bzr'' in your Home directory. Of course, you can create a directory with a different name and in a different location.
 1. Type {{{cd ubuntu_bzr}}} to change to the new directory.
 1. Type {{{bzr branch http://address/to/branch name_of_branch}}} into the Terminal. This will download the whole of the branch, which you will then be able to modify using a text editor.
  * You can get the name of the branch which you want from the [[https://code.launchpad.net/ubuntu-doc-project|list on Launchpad]]. The current development branches for each flavor of Ubuntu appear with a star by their name in that list.
  * For example, if you would like to download the Kubuntu docs for the "Karmic Koala" release, you can see from the list that the required branch is {{{lp:kubuntu-docs/karmic}}}. So, to get that branch, you would type:{{{
$ bzr branch lp:kubuntu-docs/karmic}}}
  * Using a "lp" shortcut in this way will use the SSH protocol to download the files. If you cannot use SSH for some reason, you can replace the "lp" shortcut with the full http URL of the branch. So to get the Kubuntu docs for "Karmic Koala", you would type:{{{
$ bzr branch https://code.launchpad.net/~ubuntu-core-doc/kubuntu-docs/karmic}}}
  * This process may take quite a while, as it downloads the whole of the revision history in the branch. See ''Advanced'' below for ways to speed up this process.

=== Advanced ===

If you are getting more than one branch from a particular project (for example if you plan to continue working on a future release), it will dramatically improve the speed of the download to store the revision history for each of the branches in a ''shared repository'', because the revision history for all of the branches shares a lot of data. To set up a shared repository, create a folder (e.g. "ubuntu-bzr") which you wish to use to store all the branches in as follows:{{{
$ bzr init-repo ubuntu-bzr}}} You can then create branches within this subfolder using the process described in the previous section and they will share their revision history in the shared repository you have created.

== Updating a check-out ==

You will probably want to keep up-to-date with changes made to the documentation. To download the latest updates to a branch:

 1. Open a Terminal.
 1. Change to the directory which contains your original checkout (e.g. ubuntu_bzr/name_of_branch, as above).
 1. Type {{{bzr update}}} and any updates will be downloaded.
For details on setting up and contributing, please refer to either the [[https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuDesktopGuide|Ubuntu Desktop Guide Single Page]] or the [[https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/UbuntuServerGuide|Ubuntu ServerGuide Single Page]] as appropriate. (xubuntu ?)

About The Repository

The documentation sources for the project reside in Bazaar, a revision management system created by Canonical, the company behind Ubuntu. The repository is the hub of the core document development effort. Revision control 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 branch or working copy of the documentation sources and make changes to this copy.

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 commit access can make changes to the repository. People are given access once they have consistently provided contributions and demonstrated commitment.

Key Bzr Branches

A complete list of the key Doc Team Bazaar branches is available on Launchpad.

The key branches which will be of most interest are:

Name of Branch

Description

ubuntu-docs

Ubuntu desktop help

xubuntu-docs

Xubuntu desktop help

serverguide

Ubuntu Server Guide

Generally you should use the development version for each branch.

For details on setting up and contributing, please refer to either the Ubuntu Desktop Guide Single Page or the Ubuntu ServerGuide Single Page as appropriate. (xubuntu ?)

Additional information

See the Bazaar Documentation website for comprehensive documentation. There is also a useful quick-start guide.

Next steps

Once you have downloaded a branch, the next step is to view and edit the documents contained within it. Read on to the Editing page.

Some tips for people who have been granted permissions to upload directly to the system documentation branches (by becoming members of the ubuntu-core-doc team) can be found at the /Members page. If you are just getting started with Ubuntu documentation, you don't need to read that page yet.


CategoryDocteam

DocumentationTeam/SystemDocumentation/Repository (last edited 2014-07-02 21:05:36 by belkinsa)