1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. MacPorts Upgrade
2.4. Uninstall
2.5. MacPorts and the Shell
3. Using MacPorts
3.1. The port Command
3.2. Port Variants
3.3. Common Tasks
3.4. Port Binaries
4. Portfile Development
4.1. Portfile Introduction
4.2. Creating a Portfile
4.3. Example Portfiles
4.4. Port Variants
4.5. Patch Files
4.6. Local Portfile Repositories
4.7. Portfile Best Practices
4.8. MacPorts' buildbot
5. Portfile Reference
5.1. Global Keywords
5.2. Global Variables
5.3. Port Phases
5.4. Dependencies
5.5. Variants
5.6. Tcl Extensions & Useful Tcl Commands
5.7. StartupItems
5.8. Livecheck / Distcheck
5.9. PortGroups
6. MacPorts Internals
6.1. File Hierarchy
6.2. Configuration Files
6.3. Port Images
6.4. APIs and Libs
6.5. The MacPorts Registry
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Contributing to MacPorts
7.3. Port Update Policies
7.4. Updating Documentation
7.5. MacPorts Membership
7.6. The PortMgr Team
8. MacPorts Guide Terms

The sources for this guide are kept in a Git repository on GitHub. If you spot any error or outdated information, you are encouraged to submit a pull request following the steps outlined below.

  1. First, clone the sources to your computer and switch to a new branch for your changes:

    $ git clone https://github.com/macports/macports-guide.git
    $ cd macports-guide
    $ git checkout -b my-changes origin/master
  2. Make your changes to the file in the guide/xml/ directory that corresponds to the section you want to make changes to.

    $ $EDITOR guide/xml/
  3. Verify your changes are still valid XML. First, install the required software from MacPorts if you do not already have it installed. If the make validate command reports errors, fix the XML sources until you see no more error messages.

    $ sudo port install libxslt docbook-xsl
    $ make validate
  4. Convert the guide to HTML and view the new version in your browser.

    $ make guide
    $ open guide/html/index.html
  5. Commit your changes to the local branch and describe your changes in the commit message. See also our wiki page CommitMessages that explains how to write good commit messages.

    $ git commit -a

You can submit your changes for inclusion in the guide by making a pull request on GitHub.

  1. Visit the macports-guide repository on GitHub and press the Fork button in the upper right corner. This will create a macports-guide repository in your own GitHub account. Add your new repository as a remote to your local repository, rebase your changes on top of the current upstream master and push the result to your new repository on GitHub.

    $ git remote add <username> https://github.com/<username>/macports-guide.git
    $ git pull --rebase
    $ git push <username> my-changes
  2. From here on, follow the GitHub documentation on how to create a pull request.