Contributing to Orchard Autopkg

Overview

The following are the standards we expect in order for you to productively contribute to the Orchard Autopkg repositories. We do not recommend that you attempt this on a computer that is already managed by Orchard, in this case you should only attempt the following in a VM.

Prerequisites

1. You will need a Mac running OS X 10.11 El Capitan or later.
2. You will need to be a collaborator to the Orchard Developers team on the ox-it Github. Please contact the Orchard Team for more details.

3. Install autopkg https://github.com/autopkg/autopkg/releases/latest

4. Install munki https://github.com/munki/munki/releases/latest

5. Install git https://github.com/autopkg/autopkg/wiki/Getting-Started#install-git

6. Create a github.com account if you don't have one
7. Set up a local munki repo for testing:

   cd /Users/Shared
   mkdir munki_repo
   mkdir munki_repo/catalogs
   mkdir munki_repo/manifests
   mkdir munki_repo/pkgs
   mkdir munki_repo/pkgsinfo
   mkdir munki_repo/icons

8. Create a blank site_default manifest

   /usr/local/munki/manifestutil new-manifest site_default

9. Point your test munki client at this repo:

   sudo defaults write /Library/Preferences/ManagedInstalls SoftwareRepoURL "file:///Users/Shared/munki_repo"

10. Point your autopkg installation at the munki repo

    defaults write com.github.autopkg MUNKI_REPO /Users/Shared/munki_repo

11. Add all the recipe repos currently used by Orchard to your autopkg installation with autopkg repo-add. You can find a list of the repos here.

12. Fork the ox-it/orchard-recipes and ox-it/orchard-recipe-overrides into your own github account (use the 'Fork' button in the top right corner of the repo's page) and then clone them into your autopkg dir ¹:

    git clone https://github.com/YOURUSERNAME/orchard-recipes ~/Library/AutoPkg/Recipes
    git clone https://github.com/YOURUSERNAME/orchard-recipe-overrides ~/Library/AutoPkg/RecipeOverrides

Creating an Override

1. If there is already a community recipe for an application you wish to add to the repo, you do not have to write it again, unless you are really unhappy with the way it does things (and even then you should probably contact the author with your issues to benefit the community). To check if there is a recipe out there for the software you want, you can always use autopkg to search: autopkg search appname

2. This will return a list of recipes with that name that autopkg knows about and the repos they are contained in. We are always looking for one with a .munki extension as that will allow us to import the downloaded app/pkg directly into Munki (Orchard Software Centre).

3. If you find a .munki recipe for the software you want, if the repo it is in is not currently in the Orchard recipe repos, you will need to add it with autopkg repo-add autopkg/reponame (make a note of this and include the name of the repo in your pull request later!). If you do not find a .munki recipe, please skip to "Creating Recipes" below.

4. Now cd into ~/Library/AutoPkg/RecipeOverrides. Create and checkout a git branch for your override using  git checkout -b yourbranchname  (it will help if you name the branch after the software you are trying to override).

5. Then issue autopkg make-override RecipeName.munki.recipe. autopkg will tell you where it has created the override. Now edit this file in your favourite editor according to the Override Guidelines.

6. Test your recipe by running autopkg run -vv RecipeName.munki.recipe. Ensure that the recipe downloads the latest version of the software, optionally packages it, and then imports it to your munki repo with a sensible version number.

7. Test that you have downloaded the latest version (if not the recipe you are overriding might be out of date and you may need to autopkg repo-update the repo), and that you can install and uninstall the software via munki.

8. Commit your changes to your forked repo with git add RecipeName.munki.recipe then git commit -m "Commit message here" RecipeName.munki.recipe. Finally push your changes to your origin with git push origin yourbranchname

9. To submit your override to the Orchard team for QA, please issue a pull request on github.com from your branch to the ox-it/orchard-recipe-overrides repository. The PR should contain details of any repo that needs adding for your override to work.

Creating Recipes

If there is no community recipe for the software you wish to package, you should then consider writing recipes. We generally recommend that you write 2 or 3 recipes:

1. A recipe to download the software.
2. A pkg recipe to convert it to a .pkg if necessary. You don't need this if the download is a 'drag and drop' type install e.g. an .app file inside a DMG. You can also skip this if the vendor provides a .pkg, unless you want to repackage this although this is rarely necessary and should only be done if something is broken in the .pkg.
3. A munki recipe to import it into Munki.

For more information on recipes and inheritance see https://github.com/autopkg/autopkg/wiki/Recipe-Writing-Guidelines.

Before you start writing you should:

1. Create a new branch in ~/Library/AutoPkg/Recipes with the name of the software you're writing the recipes for using git checkout -b softwarename. This will also switch you to the branch.

2. Create a folder for the recipe, unless it falls under one of the folders already in the repo (these are usually grouped together if they might need to share a common custom processor or by vendor - ask the Orchard team if you are unsure).

Please write the recipes following our Recipe Guidelines. Test that each recipe in the chain works as expected, downloading the latest version of the software, optionally packaging it and then importing it successfully into Munki with a useful version number. Please also test that you can install and uninstall your software via munki (add the pkg as an optional install in the site_default manifest). There should be no errors at any stage before you submit to the Orchard team for QA.

When you are satisfied your recipes work as intended, commit your changes with git add and git commit then push your branch to your forked repo with  git push . Then create a pull request on github.com from your branch to ox-it/orchard-recipes - give as much detail as possible in the PR about your new recipe(s).

Documenting your work

Once you have confirmation from the Orchard team that your recipe/override has been accepted into the Orchard repo and at least one version has been auto-built (please allow 24 hours) then see the package documentation page for details on writing docs for it.