documentation is out of date and sparse

[James Troup]

[Impact]

 * 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:

   http://curtin.readthedocs.io/en/latest/

[Test Case]

 n/a

[Regression Potential]

 n/a

[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
   exist

 - 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
example:

 - 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
   curtin

[Rob Thomas (xrobau)]

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?

[Andy Whitcroft (apw)]

Hello James, or anyone else affected,

Accepted curtin into xenial-proposed. The package will build now and be available at https://launchpad.net/ubuntu/+source/curtin/0.1.0~bzr425-0ubuntu1~16.04.1 in a few hours, and then in the -proposed repository.

Please help us by testing this new package. See https://wiki.ubuntu.com/Testing/EnableProposed 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 https://wiki.ubuntu.com/QATeam/PerformingSRUVerification . Thank you in advance!

[Jon Grimm (jgrimm)]

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!

[Launchpad Janitor (janitor)]

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 readthedocs.org
      (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/__init__.py
    - 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

[Martin Pitt (pitti)]

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.

[Scott Moser (smoser)]

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.