1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. Upgrade MacPorts
2.4. Uninstall MacPorts
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
6.6. Tests
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Using Git and GitHub
7.3. Contributing to MacPorts
7.4. Port Update Policies
7.5. Updating Documentation
7.6. MacPorts Membership
7.7. The PortMgr Team
8. MacPorts Guide Glossary

7.5. Updating Documentation

7.5.1. Updating the Guide

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.

We use a triangular workflow to carry changes from contributors to the project. You get the latest guide source code from the main repository on GitHub, updating your own "cloned" copy of the repository on your workstation. You make changes on your workstation, in a Git branch. You push the Git branch with your changes to your "forked" copy of the repository in your own GitHub account. Then GitHub helps turn that branch into a "pull request". MacPorts developers can review and discuss the pull request with you, and finally decide whether to accept it. This workflow is described in GitHub's guide, Forking Projects. Setting Up the Parts of the Workflow

Follow these one-time steps to set up the parts of the workflow.

  1. With your web browser, log in to GitHub. Go to this guide's main Git repository at https://github.com/macports/macports-guide.

  2. Fork your own copy of the main guide repository. Click the Fork button, at the top-right of the repository window. A dialogue may appear: "Where should we fork macports-guide?" Select your GitHub username. A message appears, "Forking macports/macports-base. It should only take a few seconds." Then GitHub moves you to a page labelled, "username/macports-guide, forked from macports/macports-guide". This page shows your "forked" copy of the repository, in your own GitHub account.

  3. On your workstation's command line, clone a copy of the main guide repository. Start in a directory which can contain the working directory for your local "clone" copy.

    $ git clone https://github.com/macports/macports-guide.git
    $ cd macports-guide
    $ git remote add username https://github.com/username/macports-guide.git
  4. Install the required ports:

    $ sudo port install libxml2 libxslt docbook-xsl-ns docbook-xml-5.0 Proposing a Change

For each change you want to make, follow these steps through the triangular workflow. In general, for one pass through this workflow, make only one change or set of related changes, in one area of the documentation. When changing different things, it is preferable to propose separate pull requests.

  1. From your workstation's command line, within your local repository directory, switch to your master branch. Then, pull the latest contents of the master repository to make your repository current.

    $ cd macports-guide
    $ git checkout master
    $ git pull origin
  2. Create a Git branch off the master branch to hold your changes. The branch-name is a concise string which describes the effect of your change. Generally, use words of ASCII letters and digits, separated by underscore '_' or dash '-', e.g. clarify_branch_creation_steps. (See git check-ref-format for detailed limitations.) If your change fixes a Trac ticket, include the ticket number in the branch name, e.g. configure-compiler-60331.

    $ git checkout -b branch-name
  3. 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/guide.xml
  4. Verify your changes are still valid XML. If the make validate command reports errors, fix the XML sources until you see no more error messages.

    $ make validate
  5. Convert the guide to HTML, and proofread the new version in your browser.

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

    $ git commit -a
  7. Push your local branch to your fork of the guide's repository on GitHub. username is your GitHub user name, under which your fork resides.

    $ git push username
  8. Next, turn your branch into a "pull request" (PR) on GitHub.

    With your web browser, go to this guide's main Git repository at https://github.com/macports/macports-guide.

    GitHub will likely show you a message that a branch on your forked repo, with your branch-name, "had recent pushes". There is a green button, Compare & pull request. Push this button.

    If GitHub does not show you that message, create the pull request yourself. Click on the "Pull requests" tab. Click on the green button, New pull request. The page changes to say "Compare changes", and there are a pair of buttons, "base: master" and "compare: master". Click on the "compare: master" button, on the right. A dialogue appears, "Choose a head ref". Type your GitHub username, followed by colon ':'. The two buttons become four, with the rightmost button reading "compare:". Click on the "compare:" button. The list of your branches appears. Click on the branch which you want to turn into a pull request. A green Create pull request button appears, slightly further down the page. Click on this button.

    A dialogue appears. The first line of your commit message is in the title, and the rest of your commit message is in the body. Edit these as necessary, then confirm. Your pull request now appears in the list of pull requests.

  9. Now, monitor your GitHub account for messages. MacPorts developers may comments and discussion about your pull request. Respond to comments as necessary.

    You may want to modify your proposed change. Modify it by repeating the "make your changes" step above, and all the subsequent steps through pushing your branch to your fork on GitHub. GitHub will incorporate changes to your fork into the pull request.

  10. Once the MacPorts developers are satisfied with your pull request, they will merge it with the main guide respository.