Using Gitify to Collaborate with Pull Requests

1. Fork a repository

Fork the repository you wish to contribute to on Github: For example, visit the Fred Theme Starter and click the fork button in the upper right.

Click the down-arrow on the green Clone or download button on a source Github project and copy the HTTPS URL which looks like https://github.com/modxcms/fred-theme-starter.git for use later. You’ll also need your fork’s SSH URL, found in the same location, for example git@github.com:your_username/your-fork-name.git.

2. Clone your fork to your MODX instance

Because git clone only works in empty directories, we’ll use a temporary tmp/ directory and move the files to the web root when done. Open an SSH connection to your working Cloud instance and execute:

cd ~/www
git clone git@github.com:your_username/your-fork-name.git tmp

This will download the theme repository into a ~/www/tmp/ directory in the Cloud. Next, move the contents of tmp/ to the correct location under www/:

rsync -av ./tmp ./

Make sure the .git/ directory and files are moved under webroot www/ directory. Once you confirm the files and directories are in the right place, go ahead and remove the tmp/ directory with rm -rf ./tmp.

3. Add the upstream remote

This is the original project. Use its HTTPS clone URL from step 1 of this tutorial to set the remote upstream:

git remote add upstream https://github.com/modxcms/fred-theme-starter.git

No changes: Sync the upstream remote to your fork

For the purposes of working with PRs, you should never commit directly to your master branch; for more information see the Feature Branches and Pull Requests: Walkthrough and Understanding the GitHub flow guides.

Before pushing any work to a feature branch, you should sync your local repository with the upstream. For more information on syncing forks see the Syncing a fork guide:

git checkout master
git fetch upstream
git merge --ff-only upstream/master  # only merges if local is clean
git push origin master               # push to your fork
gitify package:install --all
gitify build

These commands are only needed when there is a differnce between the commit version in the upstream remote and your local fork. It will not hurt to run them every time though.

Local changes: Sync the upstream remote to your fork

The following commands create your local feature branch, and commits them to the local git repo.

cd ~/www
git checkout -b my-feature   # checkout to a new branch named `my-feature`,
                             # or any other name you decide for your work
gitify extract               # extract all your local changes
git add --all                # or git add only specific changed files
git commit -m "My Changes"   # Use a more reasonable commit message

Next, we sync upstream master branch with your fork.

git checkout master
git fetch upstream
git merge --ff-only upstream/master
git push origin master

Now, we sync the feature branch with any changes from the master branch of the fork from the previous merge step.

git checkout my-feature      # checkout your `my-feature` branch again
git rebase master            # this pulls from your forked master```

This may result in conflicts that will be noted. If there are conflicts, they must be resolved before you can continue. A conflict happens when two people change the same line of code. For information on resolving conflicts, please see Github’s guide to resolving conflicts.

Finally, we build all the changes into your working MODX instance with Gitify.

gitify package:install --all
gitify build

Double check to make sure the Theme and the changes still work as expected. Then commit them to your Github fork, where it can then be submitted as a PR to the original upstream project:

git push origin my-feature   # push to your `my-feature` branch on Github to
                             # submit as a PR, per the next section below
git checkout master          # return to the master branch to start your next
gitify package:install --all # restore the `master` state to your local MODX
gitify build

Now submit the PR to the upstream project.