Skip to content

GitHub Workflow

Andrew Couling edited this page May 2, 2018 · 1 revision

Here's the workflow you'll want to use as a collaborator with the webERP project on GitHub:

Basic setup

  1. GitHub account
  2. Fork the Repository
    • On the GitHub site, navigate to the webERP project repository (https://github.com/webERP-team/webERP), and click on the 'Fork' button at the top right area of the page (as shown in the image below). This makes a copy of that repository into your own github account, which is where you will upload your changes, since you only have "write" permissions in your own repository.

  1. Clone the repository to your own computer. (see below)

Cloning a repository

  • Get the URL for the repository you're cloning
  1. Go to your GitHub account page
  2. Go to your fork of the webERP repository, e.g. https://github.com/YOURNAMEHERE/webERP
  3. On the right side of the page, you should see a button labelled 'Clone or download'. Click on the button.
  4. The pop-up box which appears will display a URL. Click on the icon next to the URL field, to copy the URL to your clipboard.

Now switch to your desktop application of choice and use that URL to clone the repository locally:

  • Command line:
  1. Pick a working directory on your PC
  2. cd into that directory
  3. Type: git clone PASTE-THAT-URL-HERE. (note the . at the end, which says "put it in the current directory")
  • SourceTree:
  1. Choose File, New Clone...
  2. In the Source Path/URL, paste the URL you copied from GitHub
  3. For the destination path, pick a folder on your PC
  4. For the bookmark name, call it whatever friendly name you want to remember this repo by. It will show up in SourceTree's bookmarks list of repositories you've got.
  5. Click Clone or OK to have it start the clone. It will take a few seconds for it to download the repository contents to your computer.

Add an upstream remote

To keep your own fork up-to-date, you'll need to periodically merge updates from the main webERP repository. This involves telling your own local (on your PC) git repository about the main webERP repository location. To do this you must add what's called an "upstream remote". (See the glossary link above for what a "remote" is.)

  • Command line:
  1. cd into the directory of the repository you're adding the remote to
  2. Type: git remote add upstream https://github.com/webERP-team/webERP.git
  3. Type: git fetch upstream
  • SourceTree:
  1. Choose Repositories from the main menu
  2. Choose Repository Settings...
  3. Click Add
  4. For Remote Name, use: upstream
  5. For the URL use: https://github.com/webERP-team/webERP.git
  6. For the GitHub username, enter your own GitHub account name
  7. Click OK
  8. Click Fetch

Making a working-branch

Any time you're going to contribute code changes, you'll want to first make a working branch. (For more on branches, see the glossary and other git references at the top of this page.) Branches are how git keeps different versions of changes separate from each other until such time as someone approves merging them together into the main branch.

Pick a branch name

Decide on a new branch name. (The branch name should be brief, but meaningful; ideally a max of 6 words, all hyphenated, no spaces.)

Make the branch

Now use that name for name-of-your-branch-here, below:

  • Command line:
  1. cd into the directory of the repository you're intending to make changes to
  2. In this example we'll be branching from the 'master' branch
  3. Type: git branch name-of-your-new-branch-here master
  4. Type: git checkout name-of-your-new-branch-here
  • SourceTree:
  1. First, make sure you're in "Log View" (View, Log View)
  2. Find where it shows upstream/master, and right-click on that row. Choose Branch... from the pop-up menu
  3. Give it the new branch name
  4. Leave the "checkout new branch" box checked
  5. Click Create Branch or OK

Make your code changes

  • Edit or create whatever files are applicable to the changes you wish to submit for consideration.
  • Test your code. Test to make sure your changes work, and that you've not broken anything else in the process.
  • Once your code is ready for submission, you'll need to commit the changes, and push them to your GitHub account and then create a Pull Request. Those steps are described below.
  • Make sure your code complies with the webERP coding standards, else it may be rejected.
  • If your code can be tested with phpunit, be sure to include those tests in your commits and pull request.

Commits

To commit your code, you must first "stage" the files which are to be included. See the git docs mentioned at the top of this page for more detailed explanation of what this means.

Once you've staged the files, then you commit them, which saves that group of changes together.

You can make multiple commits (that is, stage the files and commit them) towards any given issue. This allows you to make numerous smaller commits which are easily described in connection with the specific files that relate to those smaller changes.

  • Command line:
  1. cd into the directory of the repository you're committing from
  2. Type: git status (This will give you a list of changed/added/deleted files)
  3. Type: git add filename1.php filename2.php (and any other files, etc)
  4. Type: git commit (This will pop up your text editor where you can supply a commit message. See explanation of commit messages in the sub section below)
  5. Save the message using whatever method your text editor uses to save-and-exit
  6. This will have the commit saved locally. You can continue working and making more commits until you're ready to push them all up to GitHub (see pushing commits below)
  • SourceTree:
  1. First, go into File Status view. Click on "Working Copy" in the left nav menu under File Status. Or, use the View menu and choose File Status View. Here you'll see a list of files on-screen which have changed in some way (edits, adds, deletes). You can also see exactly what's changed by clicking on those files and viewing the "diff" on the other side of the screen.
  2. For each file that you wish to include in the current commit, highlight it in the bottom part of the window, and click the Stage Selected button on the button-bar. It may ask you to confirm that you wish to Add it. (The Windows version has a tiny up-arrow that lets you do the staging as well, instead of using the Add from the top button-bar).
  3. Once your files are all staged, click the Commit button in the button bar
  4. This will open a dialog where you can supply a commit message. See the guidance around commit messages in the next section below.
  5. Click the commit button in the bottom right. Your commit is now saved locally on your PC. You can continue making more commits until you're ready to push them all to GitHub, as described below.

About commit messages

  • The "subject" or "first line" of a commit message should be no more than 50 characters.
  • The next lines can have as much detail as you like. Consider using GitHub Markdown syntax for any formatting you might wish to include in the message. Feel free to use blank lines, and even use hyphens to create bulleted lists (hyphen plus a space)
  • If you're contributing code to help with an "Issue" that's already listed on the webERP GitHub Issues page, include that issue number in your commit message, with the hashtag in front of it, like this: #101 for issue number 101.
  • Further to the point above, if your commit "fixes" or "closes" or "resolves" an existing open issue then include the word "Fixes" before the issue number, ie: "Fixes #101" somewhere in your commit message. This will cause GitHub to close the "issue" ticket when your pull request is merged, and helps keep things tidy.
  • If you're committing code that addresses a bug reported on the webERP support forum, include the URL for that bug from the forum, so we can cross-reference it.

Suggested reading: 7 Principles for Good Commit Messages

Pushing Commits To GitHub

Now that you've made some commits to git on your local PC, you must push them to (your account on) GitHub in order to prepare to share them.

  • Command line:
  1. cd into the directory of your working repository
  2. Type: git push origin name-of-my-working-branch
  • SourceTree:
  1. Click the Push button in the top button bar.
  2. From the pulldown for "Push to repository", be sure that "origin" is selected. That's your GitHub repository, and you must push to there.
  3. Next make sure you check the box next to the branch you've been making your commits in. Uncheck all the others.
  4. Click OK
  5. That's it! Now all the commits you've made in that branch on your PC will show up in your GitHub account.

Pull Request

(You'll also see Pull Request referred to as a PR)

After you've pushed your working branch (ie: containing your new commits) to your own GitHub account, you will need to create a Pull Request in order to ask the webERP developer team to review it and consider it for inclusion in the next release.

You'll do this from your browser:

  1. Go to your GitHub account in your browser.
  2. Go to your webERP repository.
  3. You will see a green "Compare and Pull Request" button. Click it. (If it's been several hours since you did the push, it might not show the green bar. In that case, click the 'Branches' link, where you will see a Pull Request button next to each of your branches. Click the one next to the branch you want to do the pull request from.)
  4. Now you can review the collection of commits and file changes, and add a descriptive message to the pull request. If you're fixing something that's already got an open issue for it, be sure that the issue number is included in your Pull Request message. ie: #101. If you believe your Pull Request fully fixes the open issue, then say "Fixes #101", as the keyword "Fixes" helps do proper cleanup of tickets once closed. There may be multiple branches within the 'upstream remote' webERP repository, so ensure that your pull request "compare" is indeed being compared to the intended branch.
  5. Click the next green button to Create Pull Request
  6. Now you wait for others to review your code. The webERP developers (and anyone else who has clicked "Watch" on the main webERP repository) will get an alert about the pull request. Anyone wishing to reply with their opinions of what you've submitted can engage in dialog with you and one another while the code is reviewed.
  7. If your code hasn't complied with the coding standards, or has bugs or is incomplete, you may be asked to submit more commits to rectify the problems. In that case, you will repeat the steps above for making code changes, making commits, and pushing those commits to GitHub. As long as you push to the same branch on GitHub, then all those commits will automatically be included in the pull request, so reviewers can see the updates you push.
  8. Once the webERP development team decides what to do with it, they have basically three options: to accept it (merge the pull request) or defer it (until a later date) or reject it (not merge it and close the pull request). GitHub will automatically email you about all updates and comments made about your Pull Request.

Keeping Your Local Branch Current

When you or others make pull requests that are accepted into the webERP repository, that will make your own local copy be outdated. To keep current, you must periodically bring in the changes from the "upstream remote" we created earlier. (see: https://help.github.com/articles/syncing-a-fork/)

  • Command line:
  1. Type: git fetch upstream
  2. Type: git checkout master (ie: if you're going to pull changes from the master branch)
  3. Type: git merge upstream/master (merges your local copy with the upstream remote)
  4. Type: git push (brings your forked repository up-to-date)
  • SourceTree:
  1. Click the Pull button in the top button bar
  2. For Pull From Repository, choose "upstream" from the pulldown menu
  3. For Remote Branch To Pull, choose "master"
  4. Leave the "commit merged changes immediately" box checked, and the others unchecked.
  5. Click OK

Cleaning up old branches, or grabbing new branches

From time to time you and others will add or remove branches from the GitHub repositories, and you will want to keep your PC in sync with those.

  • Command line:
  1. Type: git fetch upstream
  • SourceTree:
  1. Click the Fetch button on the button bar
  2. There are 3 checkboxes. Check them all. (You could opt to not prune/delete any local branches you've created, if you want to preserve them to understand your own work history, by unchecking the corresponding box.) (You could also fetch from individual remotes manually, and prune only when fetching from upstream, but never prune when fetching from your own GitHub master)
  3. Click OK