Ubuntu Installation Guide
The Ubuntu (Server) Installation Guide is published for LTS releases only. The content is based on the Debian Installation Guide and in fact the sources are shared. Focus/branch of development will change on the prerogative of the committers.
Contributors must use the latest Ubuntu Server 16.04 release to exercise their additions/fixes to the guide.
The Ubuntu Installation Guide is maintained by people from the Ubuntu Core Development Team. Follow the above links to find the Installation Guide sources in Launchpad / Bazaar and the Ubuntu Core Development Team's project page.
The purpose of this page is to provide steps on howto contribute to the Installation Guide and to understand the process of contributing to Ubuntu Installation Guide. Feel free to expand, modify or if needed to remediate this page.
The Ubuntu Server Guide has a section on installation, too: https://help.ubuntu.com/lts/serverguide/installation.html.en
Below are sample terminal commands for installing the needed software packages used by the documentation team, downloading and editing the current documentation branch, then pushing your edits to Launchpad.
1. Install the necessary software: For editing and generation of the docs (html and pdf) the installation of the following packages is needed:
$ sudo apt install bzr docbook docbook-xml docbook-dsssl docbook-xsl xsltproc libxml2-utils yelp-tools yelp-xsl fop gnome-doc-utils make gettext w3m jadetex openjade ghostscript
For (re-)packaging some additional packages are required:
$ sudo apt install devscripts debhelper
If you have not already done so, create your SSH key, set up Launchpad, and configure Bazaar. Follow the instructions in sections 3.1, 4, and 5 here - works on Ubuntu Server the same way.
Verify that you are properly signed in to bazaar:
$ bzr lp-login <your Launchpad ID is listed>
Create a directory to store the current documentation branch and change into that directory:
$ mkdir ~/installationguide $ cd ~/installationguide
Download the current documentation branch into a directory that describes your branch, check what's there and change into that directory:
$ bzr branch lp:~ubuntu-core-dev/installation-guide/ubuntu/ changed-supported-hw Branched 541 revisions. $ ls -lad changed-supported-hw drwxrwxr-x 15 you you 4096 May 3 08:41 changed-supported-hw $ ls -la changed-supported-hw total 64 drwxrwxr-x 15 you you 4096 May 3 08:41 . drwxrwxr-x 5 you you 4096 May 3 08:40 .. drwxrwxr-x 7 you you 4096 May 3 08:41 build drwxrwxr-x 6 you you 4096 May 3 08:41 .bzr drwxrwxr-x 14 you you 4096 May 3 08:41 ca drwxrwxr-x 14 you you 4096 May 3 08:41 cs drwxrwxr-x 14 you you 4096 May 3 08:41 de drwxrwxr-x 2 you you 4096 May 3 08:41 debian drwxrwxr-x 2 you you 4096 May 3 08:41 doc drwxrwxr-x 14 you you 4096 May 3 08:41 en drwxrwxr-x 13 you you 4096 May 3 08:41 eu drwxrwxr-x 14 you you 4096 May 3 08:41 it drwxrwxr-x 21 you you 4096 May 3 08:41 po drwxrwxr-x 14 you you 4096 May 3 08:41 pt_BR -rw-rw-r-- 1 you you 858 May 3 08:41 README drwxrwxr-x 3 you you 4096 May 3 08:41 scripts $ du -hs changed-supported-hw 70M changed-supported-hw $ cd changed-supported-hw
Validation of the installation guide A validation can be done by using the builddone.sh script. Provide an architecture, a language and finally 'none' as format, like:
$ ./build/buildone.sh amd64 en none
Check if the files validate correctly or not. If they do not validate correctly (which can be the case after recent changes of the schema) either try to correct the errors by yourself, bring them up in the ubuntu-doc mailing list or the Ubuntu Core Development Team or remember them and make sure that you don't create additional error on top. Some warnings (e.g. "Column positions are not aligned") may be benign.
Sample build for verifying installation guide environment
To check and validate your entire local installation guide infrastructure you may trigger a build and create the most popular formats in the most common language like this:
$ ./build/buildone.sh amd64 en "html pdf"
To view the available xml files for editing:
$ ls -la ./en total 64 drwxrwxr-x 14 you you 4096 May 3 08:41 . drwxrwxr-x 15 you you 4096 May 3 08:41 .. drwxrwxr-x 2 you you 4096 May 3 08:41 administrivia drwxrwxr-x 2 you you 4096 May 3 08:41 appendix -rw-rw-r-- 1 you you 2655 May 3 08:41 bookinfo.xml drwxrwxr-x 2 you you 4096 May 3 08:41 boot-installer drwxrwxr-x 2 you you 4096 May 3 08:41 boot-new drwxrwxr-x 3 you you 4096 May 3 08:41 hardware drwxrwxr-x 2 you you 4096 May 3 08:41 howto drwxrwxr-x 6 you you 4096 May 3 08:41 install-methods drwxrwxr-x 3 you you 4096 May 3 08:41 partitioning drwxrwxr-x 2 you you 4096 May 3 08:41 post-install -rw-rw-r-- 1 you you 1290 May 3 08:41 preface.xml drwxrwxr-x 4 you you 4096 May 3 08:41 preparing drwxrwxr-x 3 you you 4096 May 3 08:41 using-d-i drwxrwxr-x 2 you you 4096 May 3 08:41 welcome $ find ./en -name "*.xml" ./en/using-d-i/using-d-i.xml ./en/using-d-i/modules/pkgsel.xml ./en/using-d-i/modules/powerpc/grub-installer.xml ./en/using-d-i/modules/powerpc/quik-installer.xml ...
2. Review and edit the documentation a little bit at a time. For example, to edit the section about the supported hardware for s390x, run:
$ gedit ./en/hardware/supported/s390.xml
Or just use your favorite editor. Users without a GUI will need to use CLI editors like vi or nano for editing. Save and close the file.
Check your edits - first make the html files from the xml files. This will create the html files in the directory ./build/build.out/html/):
$ ./build/buildone.sh s390x en html ...
The build process will start again with a validation of the xml files. Carefully watch this output.
Then view and verify the changes in your browser:
Local index page:
$ firefox ./build/build.out/html/index.html &
Or directly pointing to the modified content, in case you know the name or you can find it in the build output:
$ firefox ./build.out/html/ch02s01.html &
If you prefer reviewing the changes based on a PDF, just build with the 'pdf' argument and you will find the PDF document at:
Verify the HTML content - if needed refine your changes and go back to 2.
Get a summary of all changes that you made
$ bzr diff ...
3. Commit your changes and leave a brief description:
$ bzr commit -m 'Adjusted the information about the supported s390x hardware.' Committing to: /home/fheimes/work/Canonical/Docu/Ubuntu Installation Guide/installationguide/changed-supported-hw/ modified en/hardware/supported/s390.xml Committed revision 542.
If everything went fine the output of 'bzr diff' should now be empty.
Variations for the commit lines include specifying the related Launchpad bug report, if one exists:
$ bzr commit --fixes lp:<bug-#> -m 'Your brief description'
And specifying multiple bug reports, if appropriate:
$ bzr commit --fixes lp:<bug-#> --fixes lp:<bug-#> --fixes lp:<bug-#> -m 'Your brief description'
Push the branch to your Launchpad account, provide branch name as right-most part of the lp: path:
$ bzr push lp:~yourlaunchpadid/installation-guide/ubuntu-18.04-changed-supported-hw ... 32266kB 1114kB/s | Fetching revisions:Inserting stream:Estimate 74046/75981 ... Created new branch.
Note that your branch name needs to be a unique string for any subsequent pushes.
$ bzr push lp:~yourlaunchpadid/installation-guide/your-second-branch-name $ bzr push lp:~yourlaunchpadid/installation-guide/your-third-branch-name
Finalize the commit and push with:
$ bzr push lp-open All changes applied successfully. Pushed up to revision 542.
4. Submit a merge proposal to add the modifications to the main branch:
- Log in to Launchpad and click "Code" or directly open this URL in your browser:
- Click on and select the just created branch:
- Click on "Propose for merging" under "Branch merges"
- Fill out the "Propose branch for merging" form:
- Target branch: ~ubuntu-core-dev/installation-guide/ubuntu
- (you can usually leave this as it is.)
- Commit message: (Optional)
“ adjusted information about the supported s390x hardware “
- Description of the change: (Optional)
“ s390x product familiy name changed “ “ important is also that we have an architectural level set of zEC12 “
- Optionally add a reviewer to the "proposed reviewer" field - if you know one; you may just add the 'ubuntu-core-dev' team id - otherwise just leave it blank.
- Finally click the "Propose Merge" button.
- Target branch: ~ubuntu-core-dev/installation-guide/ubuntu
- The page will update with all the information you've specified and the merge is now in status review "Pending".
- In addition a mail is sent to you with the subject:
- "[Merge] lp:~yourlaunchpadid/installation-guide/ubuntu-18.04-changed-supported-hw into lp:~ubuntu-core-dev/installation-guide/ubuntu"
- Someone from the team will now sooner or later review and decide on your merge proposal.
How to update help.ubuntu.com
Typically this is done by a member of the Ubuntu Documentation Committers team.
1. Either check that the existing local branch is up to date or make a new branch.
2. Have the version specific edits been done?
Typically they have not been. If not, do them and submit an MP. While the package version and what is published on help.ubuntu.com are supposed to be the same, publish anyhow, because it can be forever before the MP is merged.
$ cd build $ build.sh
4. Fix directory names:
After the compile completes, the files will be in /tmp/manual, but with incorrect directory naming.
mv /tmp/manual/en.amd64 /tmp/manual/amd64 mv /tmp/manual/en.arm64 /tmp/manual/arm64 mv /tmp/manual/en.armhf /tmp/manual/armhf mv /tmp/manual/en.i386 /tmp/manual/i386 mv /tmp/manual/en.powerpc /tmp/manual/powerpc mv /tmp/manual/en.ppc64el /tmp/manual/ppc64el mv /tmp/manual/en.s390x /tmp/manual/s390x
5. Update your local help.ubuntu.com branch:
For a new LTS release, this would probably go to the developement area of help.ubuntu.com. Either check that the existing local branch of help.ubuntu.com is up to date or make a new branch. Make the structure, copy, then edit, the index.html file from one of the existing published directories. Move the compiled files:
mv /tmp/manual ./
For small revisions, note that the compile process uses different random numbers for internal links for each subsequent compile. Therefore it is very difficult to use "bzr diff" to check the actual differences. The workaround is too examine the differences in the text file versions.
6. Do a test publication:
If you have the ability to publish on some test web site, do so and then check everything.
7. commit and push to help.ubuntu.com.
Or, if you do not have commit rights, submit a merge proposal.
- More information can be found at: ./yourbranch/doc
- like about the build process: ./yourbranch/doc/building-ng.txt like ./yourbranch/doc/cheatsheet.xml that provides a glimpse about the document syntax
- Information about docbook in general is available here:
- Ubuntu LTS Guides:
Entry page for latest Ubuntu LTS Installation Guide: Ubuntu LTS Installation Guide - current release
Entry page for Ubuntu 18.04 LTS Installation Guide: Ubuntu 18.04 LTS Installation Guide - Bionic Beaver
Entry page for Ubuntu 16.04 LTS Installation Guide: Ubuntu 16.04 LTS Installation Guide - Xenial Xerus
Entry page for Ubuntu 14.04 LTS Installation Guide: Ubuntu 14.04 LTS Installation Guide - Trusty Tahr
Entry page for Ubuntu LTS Server Guide: Ubuntu Server LTS Guide - current release
Here are the best ways to get answers to any questions you may have: