Skip to end of metadata
Go to start of metadata

Overview

The model used for the documentation is similar to that used for the code branches and trunk but with a couple of important differences. The spaces we have are:

  • Live/Current: There is one 'live' set of documents for the latest version of the software at:
    https://wiki.opendnssec.org/display/DOCS
    (or if you are updating the SoftHSM docs then the space name is SoftHSMDOCS rather than DOCS but the process is the same). Note this doesn't have a version label - the advantage of this is that no external links need to be updated when we publish a new release. This space should only need to be updated with corrections or general improvements.
  • Archived: Documentation for previous versions will be archived to e.g. http://wiki.opendnssec.org/display/DOCS1x
  • Development/Trunk: A development version of the documentation exists at https://wiki.opendnssec.org/display/DOCSTRUNK  This should be used to make changes that apply only to the next version of the software.
  • Reference: For documentation material not linked to a specific version pages can be store in the https://wiki.opendnssec.org/display/DOCREF space and then included in the documentation using the {include:page} macro. Note that several 'hidden' shared pages (e.g. the page footer and headers) are also stored here under Browse->Pages->_InclusionsLibrary.

If you need to make a correction/extension to the live documentation (DOCS) then remember to also make it in DOCSTRUNK

Also look at the Hints and Tips page for an overview on Confluence.

Release Process

The process when publishing a new release is as follows:

  1. On the release date archive the live docs by making a copy of DOCS as DOCS1x using the instructions below.
    1. Also go to Space Admin->Themes->Customise theme and add the following to the header section {include:DOCS:_Previous_Version_Warning}
  2. Make a backup of DOCS using Browse->Advanced->HTML Export.
  3. Delete the DOCS space.
  4. Go to the DOCSTRUNK space and make a copy of this called DOCS using the instruction below. Make sure all the versioning is correct in both DOCS and DOCSTRUNK.
  5. Export the DOCS space to PDF and HTML. In the source code repository go to the branches directory for the latest release. Create a folder call 'docs' and add the PDF and HTML documentation files (co-ordinate with the source release to ensure these files are in the tarballs).
  6. In DOCREFS do the following:
    1. Go to Browse->Pages and open the _Inclusions_Library folder. Update the file _Previous_Versions_of_OpenDNSSEC_Documentation by adding a link to the version archived in step 1
    2. In the same folder update the _Downloads page by adding the files exported in step 5.

How to copy a space

Note that when this was written using 'Copy space' was actually less painful than manually renaming or moving a space....

  1. Before copying the space:
    1. Double check all the links within the documentation to be sure none are broken.
    2. Also check all the internal links for the presence of a space prefix e.g [conf.xml|DOCS:conf.xml] or a full url. (This can done by exporting the space as HTML and searching for  e.g."DOCS".) If any exist, then remove the prefix to link just directly the page name. This is done so that the link always references the page with that name within the same space. Otherwise, after the main space is copied and archived there may incorrectly be links from the archived space into the latest docs space. (The one exception to this is the link to the download action on the main page which needs DOCS as a key).
    3. Make sure the pages likely to change with the release are updated (e.g. platform support and dependancies)
  2. Go to Browse->Space Admin->Copy Space and do the actual copy 
  3. After the copy do the following in the space created by the copy:
    1. Space Admin->Themes->Customise theme. Copy the navigation pane and footer content from the original space (the plugin doesn't do this...). 
      Update the version in the navigation pane if required.
    2. Space Admin->PDF Layout and PDF Stylesheet. Copy the contents from the original space (the plugin doesn't do this either...). 
      Update the version in the Title page and page header if required. 
    3. Update the 'latest version' number on the Documentation home page if required. 

Known bugs with Confluence:

  • CONF23449: When using the {code} macro all whitespace before the first character is stripped. So formatting indented xml on the first line of a code block is impossible. The workaround I used was to have a dummy first line of 3 dots.
  • CONF20130: Any colour change to the Documentation theme->Customise Colors-> Headings is not picked up (even if the change is made in the global settings). So all headers are black, not the groovy OpenDNSSEC orange.
  • No labels