Using Gitify to Collaborate with Pull Requests
Some projects will require you to submit a Pull Request (PR) to their repository. You do this by forking the repo, making changes in a feature branch in your fork, then submitting the PR to the original project.
For the purpose of this tutorial, we’ll fork the Fred Starter Theme which is intended to be a Bootstrap 4 quickstart for theme builders. Start by signing into Github.
Fork and clone to a MODX instance¶
To start with PRs, you need to fork a repository and work on feature branches before you can submit PRs successfully.
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
2. Clone your fork to your MODX instance¶
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 email@example.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
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
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
Working with your fork¶
Syncing is important, but how you sync depends on the state of your work: if you have made changes that have not been pushed, or if you are syncing ahead of starting work (no changes).
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.
Submit a PR to the upstream project¶
Open your fork on Github. There should be a notification about creating a PR from newly created branch. Click that and submit the PR to the appropriate branch, most likely
master or as specified in the original repository README.