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

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.

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

Install the required ports:

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

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

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

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

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

Convert the guide to HTML, and proofread the new version in your browser.

$ make guide
$ open guide/html/index.html

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

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

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.

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.

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