UbuntuInstallationGuide

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

Howto contribute

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: 

./build/build.out/install.en.pdf

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:
    • lp:~yourlaunchpadid/installation-guide/ubuntu-18.04-changed-supported-hw
  • 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.
  • 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.

3. Compile: 

$ 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.

Further information

Getting help

Here are the best ways to get answers to any questions you may have:

Deadline

The deadline is usually the Documentation String Freeze, please check these pages for any updates: DocumentationStringFreeze and BionicBeaverReleaseSchedule

DocumentationTeam/SystemDocumentation/UbuntuInstallationGuide (last edited 2020-04-23 20:07:05 by dsmythies)