Contribute to an Existing Manifest

This page provides the best practice process for updating an existing manifest. For those less comfortable on the command-line and/or with git in general, you may find it useful to use the Github Desktop app. If you're new to Github Desktop, here's some helpful documentation.

Make sure you've enabled the Developer menu in ProfileCreator.

For those less familiar with git, the steps below are meant to be a guide for "best practices". They are by no means meant to be barriers to contributing. The best way to learn is by doing and working through the struggles therein. Especially if you are contributing for the first time, you'll find it easier to use existing preferences and/or other manifests as models. Refer to Manifest Format for more information.

If you're struggling, you can always shoot a message in the #profilemanifests channel on the MacAdmins Slack.

Know that some manifests have many of the same preferences, like Google Chrome, Brave, and Microsoft Edge, as well as the Restrictions payloads for macOS, iOS, and tvOS. As such, if changes are being made to any one of these they likely will need to be made elsewhere. See Related Manifests for more info.

1) Fork ProfileManifests

1. Fork the project on Github.
   • Helpful guide
2. Clone your fork to your local machine.
   • Helpful guide
3. Create a new branch from 'master' to work from.
   • Helpful guide

2) Install & Enable pre-commit

Pre-commit is a way of catching common errors and helping to ensure standardization within a code project.

4. Install pre-commit via your preferred method.
5. Once, installed open a Terminal window and navigate to your ProfileManifests fork.
6. Enable pre-commit by running: pre-commit install.

3) Access & Copy the Desired Manifest

Note that manifests are located in & can be loaded from 2 different places:

• Within the ProfileManifests.framework built in the ProfileCreator app.
  • These versions are in binary format
• In ~/Library/Application Support/ProfilePayloads
  • These versions are in xml format

7. Navigate to your local fork of the ProfileManifests repo and find the applicable manifest file.

You can more easily determine the name of this file by accessing the desired payload in ProfileCreator and clicking on the name at the top.

8. Make a copy of the manifest in ~/Library/Application Support/ProfilePayloads within the same manifests folder. This is the copy you'll work from.

4) Make Changes

9. Open the copied manifest in your text editor of choice.

• If you don't have a text editor other than TextEdit, BBEdit, Sublime Text, Atom, and VSCodium are all free & fairly popular.

10. Update the pfm_last_modified date. If you will be adding additional preferences, you should also bump the pfm_version (not pfm_format_version). It is not necessary to bump the pfm_version otherwise.

ProfileCreator uses both pfm_last_modified & pfm_version to determine the newest manifest to use.

11. Add or update any needed preferences and save your changes to the manifest. Refer to the Manifest Format document as needed.
12. In ProfileCreator, select Developer > Reload Payload Manifest from the menu bar to see your changes.

It can be beneficial to focus on a single preference at a time. Once you've made the desired changes and it's appearing in ProfileCreator correctly, committing each preference change to your fork can make it easier to read for those reviewing your code. When you make a lot of changes at once, it's easy to miss something or get something wrong.

5) Copy & Commit Changes

13. With your changes made, copy the updated manifest to the corresponding folder in your ProfileManifests fork.
14. Commit the changes to your branch.

An example commit message: 'Add <preference_key> to <name_of_manifest>.plist'

15. Make any necessary additional changes, save them, reload ProfileCreator, and commit until finished.
16. Push your local changes up to your fork on Github.

6) File a Pull Request (PR)

14. Once all changes have been pushed to your branch on Github, navigate to the ProfileManifests project.
15. Having pushed your branch, you should see a button to create a Pull Request. Click this.
16. Provide any applicable details in the PR description, including the documentation / URL you referenced (if not already included in pfm_documentation_url) and submit it.

Once your changes have been reviewed & your PR is accepted, you can safely delete the branch in your fork.

7) Keep Your Fork Up-To-Date

Should you want to continue contributing, as additional changes are made to the project by other contributors, your fork will no longer be in sync with the master branch of ProfileManifests. Before you can make any additional changes, make sure to complete these steps to sync your fork.

Alternatively, there is a 'Fetch upstream' button that you can click right from your fork in Github.