Contributing to Orchard Autopkg

The following are the standards we expect in order for you to productively contribute to the Orchard Autopkg repositories.

Prerequisites

1. You will need a Mac running OS X 10.10 Yosemite

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

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

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

5. Create a github.com account if you don't have one
6. 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

7. Point your autopkg installation at the munki repo

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

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

9. 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, please skip to "Creating Recipes" below.

4. Now cd into ~/Library/AutoPkg/RecipeOverrides and create and checkout a git branch for your override.  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. 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

8. 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 a recipe to download the software, a pkg recipe to convert it to a .pkg if necessary (you can skip this part if the download is a 'drag and drop' type install of an app inside a DMG, or if the vendor provides a .pkg (unless you want to repackage this somehow, although this is rarely necessary and should only be done if something is broken in the .pkg)), and a munki recipe to import it into Munki. For more information on recipe inheritance see https://github.com/autopkg/autopkg/wiki/Recipe-Writing-Guidelines.

• Before you start writing you should create a new branch in ~/Library/AutoPkg/Recipes and switch to it git branch checkout -b yourbranchname (name the branch after the software you're writing the recipes for). 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).

• 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. 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).