Package Documentation

Overview

The Orchard team aspire to have public-facing documentation for all software packages distributed via munki and the Orchard Software Centre. This documentation is intended both for end users and for IT support staff, and can be found by browsing the links in the Display Name column of the software list. The documentation follows a simple template which embeds a dictionary of key/value pairs into the static wiki page for the software.

Documenting a package

1. Once the software is in the production repo, it will appear in the software list. Click on the Display Name of the software to take you to an empty wiki page.

2. Create this page from the template Software/SoftwareTemplate

   • Once created (as noted in the comments at the top of the page):

     • update references to **DISPLAY_NAME** with the package display name (e.g. Amazing Widgets)

     • update references to **NAME** with the package name (e.g. Amazing_Widgets)

3. Click save changes, we will come back to this page momentarily.

4. Now you can click on the link at the end of the 'Generated from InfoDict' text on the saved page to take you to the information dictionary for this software pkg.

5. Create this page from the template Software/InfoDictTemplate. The comments in the template should help you fill out the fields, but to clarify:

   • DisplayName:: should be display_name from the munki pkginfo

   • Description:: should be description from the munki pkginfo

   • For the LicenceStatus:: field choose from the options listed in the comments. e.g. if the software is completely free and open source, enter foss

   • For LicenceURL:: either include a relevant URL to licensing information or copy and paste the link to the anchor provided, and detail the licence situation later on the page generated above from the SoftwareTemplate

   • For BuildType:: enter autopkg if a recipe or override has been created, otherwise manual if the software has been built some other way

   • For BuildInfo:: If you entered autopkg above a link to the .munki recipe in one of the ox-it recipe repos is enough (even if this is a private repo), otherwise copy and paste the link to the anchor provided, and detail the build prodess later on the page generated above from the SoftwareTemplate

   • Developer:: should be developer from the munki pkginfo

   • For SupportStatus:: choose from one of the options listed in the comments. For instance if you were part of Orchard for ITSS you would put "funded by <YOURDEPARTMENT>" here.

   • For SupportedOSVers:: glean the supported OS versions from the pkginfo's min_os_version and max_os_version keys and format it according to the options in the comments, or put all if nothing is specified there.

   • For RestartRequired:: enter yes if the pkg will cause the Orchard Software Centre to log the user out to install and reboot, otherwise no

   • For Requires:: enter all the name's of the pkgs in the requires key from the pkginfo, separated by spaces if they are an array.

   • For UpdateFor:: enter all the name's of the pkgs in the update_for key from the pkginfo, separated by spaces if they are an array.

6. Save this page and go back to the software's main documentation page.

   • You should see the fields you added to the InfoDict populating the information here now.

   • Edit this page adding any further information required, and delete the anchors and headings for the sections you do not need to fill out.
7. Once you are happy, save the edits to the software page.

CategoryWikiToDo