Repository
|
Size: 9498
Comment: dumping from DocumentationTeam/Repository
|
← Revision 28 as of 2014-07-02 21:05:36 ⇥
Size: 4983
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #title The System Documentation Repository |
|
| Line 2: | Line 4: |
| <<Include(DocumentationTeam/MeetingBanner)>> | |
| Line 3: | Line 6: |
| ||<tablestyle="float:right; font-size: 0.9em; width:30%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<TableOfContents(2)>>|| | ||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<TableOfContents(3)>>|| |
| Line 7: | Line 10: |
| The documentation sources for the project reside in [[http://bazaar-vcs.org|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. | The documentation sources for the project reside in [[http:bazaar.canonical.com|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. |
| Line 11: | Line 14: |
| A list of Doc Team Bazaar branches is available on [[https://code.launchpad.net/ubuntu-doc|Launchpad]]. | == Key Bzr Branches == |
| Line 13: | Line 16: |
| == Installing Bazaar == | A complete list of the key Doc Team Bazaar branches is available on [[https://code.launchpad.net/~ubuntu-core-doc|Launchpad]]. |
| Line 15: | Line 18: |
| In order to use Bazaar, install the {{{bzr}}} package. | The key branches which will be of most interest are: |
| Line 17: | Line 20: |
| 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. | ||<tablestyle="border:1px solid"> '''Name of Branch''' || '''Description''' || || [[https://code.launchpad.net/~ubuntu-core-doc/ubuntu-docs|ubuntu-docs]] || Ubuntu desktop help || || [[https://code.launchpad.net/~ubuntu-core-doc/xubuntu-docs|xubuntu-docs]] || Xubuntu desktop help || || [[https://code.launchpad.net/~ubuntu-core-doc/serverguide|serverguide]] || Ubuntu Server Guide || |
| Line 19: | Line 25: |
| == Generating SSH keys == If you are using bazaar over ssh, you might also need to generate ssh keys and add it to launchpad, and add a ~/.ssh/config to allow you to connect to launchpad with a different user name than your Ubuntu Linux account. |
Generally you should use the development version for each branch. |
| Line 22: | Line 27: |
| 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/~<your launchpad username>/+editsshkeys and update your ssh keys. 3. Add/Edit ~/.ssh/config to contain the following {{{ Host *launchpad.net User <your launchpad username>}}} |
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 ?) |
| Line 29: | Line 29: |
| == Checking-out the docs == | <<Include(DocumentationTeam/SystemDocumentation/BzrCommon)>> |
| Line 31: | Line 31: |
| To make changes to documentation held in a Bazaar branch, you first need to download a copy onto your computer. These instructions cover downloading the ''ubuntu-changes'' branch of the gnome-user-docs. | == Getting the docs == |
| Line 33: | Line 33: |
| 1. Open a Terminal by pressing '''Applications''' -> '''Accessories''' -> '''Terminal'''. | 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. On a GUI based system, open a Terminal by pressing '''Applications''' -> '''Accessories''' -> '''Terminal'''. Of course, a server based system only has terminals. |
| Line 36: | Line 40: |
| 1. Type {{{bzr branch http://address/to/branch name_of_branch}}} into the Terminal (choose the branch which you want to download from the [[https://code.launchpad.net/ubuntu-doc|list on Launchpad]]). This will download the whole of the branch, which you will then be able to modify using a text editor. 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 === There are several ways to improve the speed of downloading branches. 1. If you wish to check out more than one branch, it is more efficient to store the revision history for 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 --trees --format=dirstate-with-subtree 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. 1. Lightweight checkouts. You can avoid downloading the full revision history for a branch using a lightweight checkout:{{{ $ bzr checkout --lightweight http://address/to/branch name_of_branch}}} For more information see the [http://bazaar-vcs.org/CheckoutTutorial bzr website]. 1. Downloading a tarball of the revision history. To improve download speed, you can download a compressed tarball which you can use to create a shared repository with the revision history for all the branches. The tarball can be downloaded [[http://calcium.ubuntu.com/~mdke/ubuntu-doc-initial.tar.bz2|here]] and is currently 420MB (a saving of 200MB or so on the full shared repository). After downloading the tarball, extract the contents into the folder you wish to use for a shared repository. You will then have full revision history for all the branches. To get a updated working tree for any branch, simply run:{{{ $ cd name_of_branch $ bzr checkout . $ bzr update}}} |
1. Type {{{bzr lp: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. * Current development examples: . {{{$ bzr branch lp:ubuntu-docs}}} . {{{$ bzr branch lp:serverguide}}} . {{{$ bzr branch lp:xubuntu-docs}}} * Previous release examples: . {{{$ bzr branch lp:ubuntu-docs/precise}}} . {{{$ bzr branch lp:serverguide/precise}}} . {{{$ bzr branch lp:xubuntu-docs/precise}}} * 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. |
| Line 54: | Line 54: |
| You will probably want to keep up-to-date with changes made to the documentation. To download the latest updates to ''ubuntu-changes'': | You will probably want to keep up-to-date with changes made to the documentation. To download the latest updates to a branch: |
| Line 58: | Line 58: |
| 1. Type {{{bzr merge}}} and any updates will be downloaded. | 1. Type {{{bzr update}}} and any updates will be downloaded. |
| Line 60: | Line 60: |
| == Making a patch == | == Next steps == |
| Line 62: | Line 62: |
| First, double check your work. Here is a good procedure to follow: | Once you have downloaded a branch, the next step is to view and edit the documents contained within it. Read on to the '''[[DocumentationTeam/SystemDocumentation/Editing|Editing]]''' page. |
| Line 64: | Line 64: |
| 1. Change to the scripts directory in the branch you are working on. 1. Validate the file you changed.{{{ ./validate.sh address/to/file.xml}}} 1. Open the file in yelp and visually double check your work.{{{ yelp address/to/file.xml}}} It seems like a lot of extra work, but it's worth it. You will save yourself the embarrassment when you catch your own mistakes before someone else does. '''Note:''' It is generally a better idea to make several small changes and send them individually than it is to make one big change. Preparing a patch is easy. You can make a patch for a single file or a group of files that have been modified. 1. Change the present working directory to the root of your working copy. 2. Issue the {{{bzr update}}} command. This updates your working copy with changes from the repository. Check for conflicts and resolve them. 3. Issue the {{{bzr status}}} command. This shows the status of files. Ensure that all conflicts are resolved. 4. Issue the command {{{bzr diff > diffname.txt}}} (!) If you wish to include your own name and a narrative for your change, you should create a ''bundle'' rather than a patch. To do this, issue these commands instead of the command at step 4 above:{{{ $ bzr commit -m "your narrative here" $ bzr bundle > diffname.txt}}} This creates the file {{{diffname.txt}}}, which contains the differences between the working copy and repository revisions of the modified files. You should send the patch/bundle to the team [[DocumentationTeam/Contact|mailing list]] or attach it to a relevant bug report. If you have a mentor, copy them into the email and ask them to review it. For more information about working with bzr, see the [[http://bazaar-vcs.org|bzr website]]. After you get used to DocBook, bzr and the DocumentationTeam, you are very likely to be offered an account so that you can write to the repository as well. == Applying a patch == At times you may need to apply a patch to your copy of the docs that someone else has created but that has not been committed yet. This allows people to review changes and make suggestions before a patch is committed. 1. Save the patch file in a suitable location, like {{{ubuntu-doc/patches/}}} for example. 2. Change to the relevant branch on your computer:{{{ cd ubuntu-doc/ubuntu-hardy }}} 3. Apply the patch file{{{ patch -p0 < patches/patch.diff }}} That's it! However, depending on how the patch was created, you made need to cd into the directory where the actual file to be patched resides. Simply cd into that directory, (e.g. {{{ubuntu-hardy/ubuntu/internet/C}}}) before applying the patch. Bzr bundles are even easier to apply using the command{{{ $ bzr merge address/to/bundle}}} == See a list of changed files == To see a list of all of the files which you have changed in the current directory, type the following: {{{bzr diff | grep ===}}} == Command summary == To see a simple one line reminder for each of the commands outlined here, type the following in Terminal: {{{bzr help}}} == Publishing changes == Members of the ubuntu-core-doc team can publish their changes directly to the branches. To do this, run{{{ bzr push bzr+ssh://username@bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-doc/name_of_branch}}} We recommend that members use the concept of ''Bound Branches'' so that the {{{bzr commit}}} command sends your changes directly to the appropriate branch on Launchpad. You can bind a branch by running{{{ bzr bind bzr+ssh://me@bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-doc/name_of_branch}}} For more information about using bound branches, see [[http://bazaar-vcs.org/BzrUsingBoundBranches|the bzr website]]. == Additional information == See the [[http://bazaar-vcs.org/Documentation|Bazaar Documentation website]] for comprehensive documentation. There is also a useful [[http://bazaar-vcs.org/QuickHackingWithBzr|quick-start guide]]. |
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. |
Inclusion deadlines for Impish – String Freeze: September 16, 2021 / Non-language packs: September 30, 2021 |
Contents |
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 desktop help |
|
Xubuntu desktop help |
|
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 ?)
Tools for Ubuntu Documentation Work Flow
To be able to contribute to Ubuntu Documentation some tools will be required. So we will start by installing the following:
sudo apt install bzr xsltproc libxml2-utils yelp-tools yelp-xsl make
The command will install the following software (and possibly many additional dependent packages):
- bzr – distributed version control. Bazaar, a new way of working with packages for Ubuntu that will make it easy for many developers to collaborate and work on the same code while keeping it trivial to merge each other’s work.
- xsltproc - XSLT command line processor.
- libxml2-utils - XML utilities.
- yelp-tools - Yelp documentation tools.
- yelp-xsl - XSL stylesheets for the yelp help browser.
- make - a utility for Directing compilation.
Since 17.10 the Desktop documentation mostly uses the gnome docs, directly from their related packages. Therefore a full multi-language build of the html is typically done on a desktop computer with all languages installed:
sudo apt install gnome-user-docs* gnome-getting-started-docs*
Xubuntu and the Serverguide use Docbook, and therefore require additional packages:
sudo apt install docbook docbook-xsl
- docbook - standard SGML representation system for technical documents
docbook-xsl - stylesheets for processing DocBook XML to various output formats
Additionally only the serverguide project requires another couple of packages:
sudo apt install fop gnome-doc-utils
- fop - XML formatter driven by XSL Formatting Objects
- gnome-doc-utils - collection of documentation utilities for the GNOME project
Create your SSH key
SSH stands for Secure Shell, and it is a protocol that allows you to exchange data in a secure way over a network. It is common to use SSH to access and open a shell on another computer, and to use it to securely transfer files. For our purposes, we will mainly be using SSH to securely upload source packages to Launchpad.
No previous SSH key
To generate an SSH key, enter:
ssh-keygen -t rsa
Accept the default file name id_rsa. For security purposes, it is highly recommended that you use a pass-phrase.
SSH key generated previously
If you already have an id_rsa SSH key that you use for some other purpose but accessing Launchpad, there are two options:
Don't generate another key, but copy the public key from the already existing id_rsa.pub when asked to upload your key to Launchpad.
Get set up to work with Launchpad
Launchpad is a system used to keep track of many aspects of open-source development. Launchpad's features include code hosting, bug tracking, translation, feature blueprints and a community-based answer tracker. This section will outline how to get setup with Launchpad to allow you to contribute the Ubuntu.
To find out more about Launchpad click here
Get a Launchpad account
The following steps will guide you through creating a Launchpad account:
Visit the Login/Register Page
- Enter your email and select "I am a new Ubuntu One user:"
- Enter your details as requested, agree to the "Terms of Service" and click "Create Account:
- Confirm your account by clicking on the link given in a confirmation email set to the email you provided
It is encouraged for you to use your real name here so that your Ubuntu developer colleagues will be able to get to know you better. You are now ready to contribute to Ubuntu through Launchpad!
Upload your SSH key to Launchpad
Open https://launchpad.net/~/+editsshkeys in a web browser, also open ~/.ssh/id_rsa.pub in a text editor. This is the public part of your SSH key, so it is safe to share it with Launchpad. Copy the contents of the file and paste them into the text box on the web page that says “Add an SSH key”. Now click “Import Public Key”. For more information on this process, visit the creating an SSH keypair page on Launchpad.
Configure Bazaar
Bazaar is the tool we use to store code changes in a logical way, to exchange proposed changes and merge them, even if development is done concurrently. It is used for the new Ubuntu Distributed Development method of working with Ubuntu packages. Use bzr whoami and bzr launchpad-login to tell Bazaar who you are. For example:
bzr whoami "Bob Dobbs <subgenius@example.com>" bzr launchpad-login subgenius
bzr whoami will tell Bazaar which name and email address it should use for your commit messages. With bzr launchpad-login you set your Launchpad ID. This way code that you publish in Launchpad will be associated with you. Note: If you can not remember the ID, go to https://launchpad.net/~ and see where it redirects you. The part after the “~” in the URL is your Launchpad ID.
Bazaar Explorer
Even if the rest of this page describes terminal commands for working with Bazaar branches, there are GUI applications available that appeal to some contributors. One such application that you may want to try is Bazaar Explorer.
sudo apt install bzr-explorer
Additional information
See the Bazaar Documentation website for comprehensive documentation. There is also a useful quick-start guide.
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.
On a GUI based system, open a Terminal by pressing Applications -> Accessories -> Terminal. Of course, a server based system only has terminals.
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.
Type cd ubuntu_bzr to change to the new directory.
Type bzr lp: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 list on Launchpad. The current development branches for each flavor of Ubuntu appear with a star by their name in that list.
- Current development examples:
$ bzr branch lp:ubuntu-docs
$ bzr branch lp:serverguide
$ bzr branch lp:xubuntu-docs
- Previous release examples:
$ bzr branch lp:ubuntu-docs/precise
$ bzr branch lp:serverguide/precise
$ bzr branch lp:xubuntu-docs/precise
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.
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:
- Open a Terminal.
- Change to the directory which contains your original checkout (e.g. ubuntu_bzr/name_of_branch, as above).
Type bzr update and any updates will be downloaded.
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.
DocumentationTeam/SystemDocumentation/Repository (last edited 2014-07-02 21:05:36 by belkinsa)