documentation is out of date and sparse

Bug #1351085 reported by James Troup
This bug affects 3 people
Affects Status Importance Assigned to Milestone
curtin (Ubuntu)

Bug Description


 * Curtin documentation is out-of-date and sparse.

   Curtin has been updated to include detailed documentation about
   its configuration, features, function and implementation. The
   latest configuration is now available at:

[Test Case]


[Regression Potential]


[Original Description]

The only documentation I could find curtin is doc/topics/overview.rst
in the source. It has several problems:

 - It talks about a final_commands hook which doesn't exist AFAICS

 - It doesn't talk about the late_commands hook which definitely does

 - It refers to both TARGET_MOUNT_POINT and TARGET_MP; I suspect only
   one exists

 - It has confusing examples which I don't think work/make sense, e.g:

| config_hook: {{TARGET_MP}}/opt/curtin/config-hook

The documentation is also pretty sparse in many ways, it doesn't for

 - Explain that the config is YAML

 - Explain other basic things about the config, e.g. what are the keys
   for hooks? Do the names matter? Does ordering matter?

 - Explain why you might want to use a list versus scalar for values

 - Explain how one might use YAML features such as 'repeated notes' to
   include data in the config that's intended for files

 - Explain that you probably want to use -- with curtin in-target to
   stop options of what you're trying to run being swallowed up by

Related branches

James Troup (elmo)
summary: - documentation is out of date
+ documentation is out of date and sparse
Changed in curtin:
status: New → Confirmed
importance: Undecided → High
Revision history for this message
Rob Thomas (xrobau) wrote :

After having some quick instructions on some non-obvious ways of doing things, I offered to write some documentation to ease other people.

However, it's amazingly difficult for a regular guy to assist with documentation with a pull request.

May I suggest splitting the documentation into its own git repository, and letting people do pull requests?

Ryan Harper (raharper)
description: updated
Revision history for this message
Andy Whitcroft (apw) wrote : Please test proposed package

Hello James, or anyone else affected,

Accepted curtin into xenial-proposed. The package will build now and be available at in a few hours, and then in the -proposed repository.

Please help us by testing this new package. See for documentation how to enable and use -proposed. Your feedback will aid us getting this update out to other Ubuntu users.

If this package fixes the bug for you, please add a comment to this bug, mentioning the version of the package you tested, and change the tag from verification-needed to verification-done. If it does not fix the bug for you, please add a comment stating that, and change the tag to verification-failed. In either case, details of your testing will help us make a better decision.

Further information regarding the verification process can be found at . Thank you in advance!

tags: added: verification-needed
Andy Whitcroft (apw)
Changed in curtin (Ubuntu):
status: New → Fix Released
Changed in curtin (Ubuntu Xenial):
status: New → Fix Committed
Revision history for this message
Jon Grimm (jgrimm) wrote :

I've verified the new docs are published, pushing to verification-done so it unblocks mirgration for an SRU for maas. Further recommendations or desires for documentation should be filed in a new bug. Thanks!

Changed in curtin:
status: Confirmed → Fix Committed
tags: added: verification-done
removed: verification-needed
Revision history for this message
Launchpad Janitor (janitor) wrote :

This bug was fixed in the package curtin - 0.1.0~bzr425-0ubuntu1~16.04.1

curtin (0.1.0~bzr425-0ubuntu1~16.04.1) xenial-proposed; urgency=medium

  [ Scott Moser ]
  * debian/new-upstream-snapshot: add writing of debian changelog entries.

  [ Ryan Harper ]
  * New upstream snapshot.
    - unittest,tox.ini: catch and fix issue with trusty-level mock of open
    - block/mdadm: add option to ignore mdadm_assemble errors (LP: #1618429)
    - curtin/doc: overhaul curtin documentation for
      (LP: #1351085)
    - curtin.util: re-add support for RunInChroot (LP: #1617375)
    - curtin/net: overhaul of eni rendering to handle mixed ipv4/ipv6 configs
    - curtin.block: refactor clear_holders logic into block.clear_holders and
      cli cmd
    - curtin.apply_net should exit non-zero upon exception. (LP: #1615780)
    - apt: fix bug in disable_suites if sources.list line is blank.
    - vmtests: disable Wily in vmtests
    - Fix the unittests for test_apt_source.
    - get CURTIN_VMTEST_PARALLEL shown correctly in jenkins-runner output
    - fix vmtest check_file_strippedline to strip lines before comparing
    - fix whitespace damage in tests/vmtests/
    - fix dpkg-reconfigure when debconf_selections was provided.
      (LP: #1609614)
    - fix apt tests on non-intel arch
    - Add apt features to curtin. (LP: #1574113)
    - vmtest: easier use of parallel and controlling timeouts
    - mkfs.vfat: add force flag for formating whole disks (LP: #1597923)
    - block.mkfs: fix sectorsize flag (LP: #1597522)
    - block_meta: cleanup use of sys_block_path and handle cciss knames
      (LP: #1562249)
    - block.get_blockdev_sector_size: handle _lsblock multi result return
      (LP: #1598310)
    - util: add target (chroot) support to subp, add target_path helper.
    - block_meta: fallback to parted if blkid does not produce output
      (LP: #1524031)
    - commands.block_wipe: correct default wipe mode to 'superblock'
    - tox.ini: run coverage normally rather than separately
    - move uefi boot knowledge from launch and vmtest to xkvm

 -- Ryan Harper <email address hidden> Mon, 03 Oct 2016 13:43:54 -0500

Changed in curtin (Ubuntu Xenial):
status: Fix Committed → Fix Released
Revision history for this message
Martin Pitt (pitti) wrote : Update Released

The verification of the Stable Release Update for curtin has completed successfully and the package has now been released to -updates. Subsequently, the Ubuntu Stable Release Updates Team is being unsubscribed and will not receive messages about this bug report. In the event that you encounter a regression using the package from -updates please report a new bug using ubuntu-bug and tag the bug report regression-update so we can easily find any regressions.

Revision history for this message
Scott Moser (smoser) wrote : Fixed in Curtin 17.1

This bug is believed to be fixed in curtin in 17.1. If this is still a problem for you, please make a comment and set the state back to New

Thank you.

Changed in curtin:
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers