Using Git and GitHub

Git is the distributed version control system used by MODX for source code collaboration and version control. Like MODX, it's free and open source.

GitHub is where MODX Git repositories are hosted. GitHub is a service for "secure source code hosting and collaborative development" but also forms a social network for coders.

Read more about GitHub's repository hosting but also be sure to bookmark their excellent Git Reference site.

Overview

Here's an overview of the workflow you'll be using to contribute changes to any MODX repository. It will help to understand this first before diving in to more detail.

Fork
First, you will fork a MODX code repository to your own GitHub account. This is "your fork". You will be publishing your code contributions (commits) to your fork, not directly to the modxcms repository. (This is what makes Git distributed, whereas SVN is centralized around one repository.)

Then, in order to work with your fork, you will need a local copy, or clone of it.

Here's GitHub's tutorial on forking a repo and making a local clone of it.


Branch and code
All work on a single issue (bug or feature) is to be done on a feature branch.
git checkout -b bug-1111

You will make changes to a file or files. Coding.. yay! You make one or several commits on that branch. (Multiple commits can really help keep things organized in certain circumstances.)

Along the way, or when the work is done, you push the branch to your fork. You'll be able to see your feature branch and your commits on the GitHub site.

git push myRepo bug-1111

Note: Making sure your work and your commits are based on "fresh" code will help you avoid problems and help integrators understand, review and integrate (or feed back on) your work.


Pull Request
When you're ready to contribute the commit or commits from your branch, you'll issue a Pull Request from your GitHub account.

Your Pull Request may be accepted as-is by an integrator or they may make changes or comment, ask questions etc. GitHub facilitates communication with in-line code comments as well as a simple discussion thread on Pull Requests.

Community Contributor's Guide 

With that basis in the workflow, your next step is to read the Community Contributor's Guide to understand the branching model MODX is using and for more detail on putting it into practice.

More 

  1. Community Contributor's Guide
  2. Git FAC (Frequently Accessed Commands)
  3. xPDO GitHub Contributor's Guide

Related

Comment Policy

These comments are not for usage questions or support. See below for support options.

Comments intended add specific value for other users with this document are welcome! Have a suggestion to improve this document? Suggest an edit (requires GitHub account). Have suggestions for code changes or feature requests? .

Support Options

If you need assistance, you can get it via the MODX Forums or the MODX Community Slack.

Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab) or become an editor of the MODX Documentation.