Cheat Sheet

To check out a new branch based on the repo's stable branch (this branch would be named "contribution-name"):

git checkout -b contribution-name origin/ojs-stable-2_4

Introduction

The Public Knowledge Project uses Github to make several repositories available to interested parties who wish to contribute. The repositories are publicly accessible, but if you would like to contribute modifications or enhancements, you will need to configure your own copies of the official repositories. The typical life cycle of a contribution is this:

Something is identified, which needs to be fixed, or contributed (in the case of a new feature or enhancement).

The modifications are made to your own copy of our repositories, and tested to make sure that things work as they should.

A request is issued to us, so that we then become aware of what you’d like to contribute.

Someone from the PKP development team will review your work, and either merge it into our own repositories, or comment on your contribution and possibly suggest enhancements or minor modifications before it is accepted.

Once accepted, the request is closed. The cycle can then begin again with a new code enhancement.

This document will attempt to outline the necessary steps in order to achieve the scenario described above.

All of the PKP repositories can be found from the organization page on Github, available at https://github.com/pkp

As you will see, each project (OJS, OMP, OCS, Harvester) is listed, with links to those individual repositories. In addition, there is a repository called “PKP-lib” which contains the shared library code used by all of the PKP software products. To obtain a working installation of any of the PKP products, you will need both the repository for the product and also the PKP-lib repository. The PKP-lib repository will be configured as a sub module. This document will explain how to do that.

Create your Github Account and fork the repositories

We shall use Open Journal Systems, as an example, in this document but the procedure is the same for any of the products. In order to create your own ‘fork’ of the official OJS repository, you will first need to register for a free Github account. Once you have registered and signed into your account, navigate to the repository you wish to fork. For the OJS repository, this would be https://github.com/pkp/ojs

In the top right of the screen, click the button labelled ‘fork’. The process will take just a moment to run, and when it is completed, you will be redirected to the repository page for your own fork.

Repeat the same process for the PKP-lib repository, at https://github.com/pkp/pkp-lib. You will need both repositories in order to run a working installation of any of the PKP software products.

Once you have done this, you should see two repositories listed on your Github home page.

Configure your local development environment

At this point, we will need to configure your local development environment to use these two forked repositories. This document assumes that you have access to a command line shell environment (e.g. a terminal window on Linux, or an application like iTerm under Mac OS X), which we shall be using for the rest of this exercise. You will need to be be familiar with a command line text editor and basic shell commands in order to get the most out of this document. For the remainder of this document, commands that are meant to be typed will be shown in a monospaced font, and preceded by a dollar sign ($). This dollar sign represents your command prompt and is not meant to be typed when you are reproducing the commands.

First, you will need the Git application for your development environment. Git is available for many different platforms. Please download and install the most suitable one: http://git-scm.com/downloads

Once Git is installed, you will need to configure it. There are two variables that should be set, in order to let Github correctly tag commits that you make to your own repositories. Open your terminal program and run the following two commands, replacing the necessary information with your own.

Clone the PKP Repositories

Once this is done, it is time to clone the main repository representing the project you wish to contribute to. You will need the URL to your repository. To get this URL, visit the home page for your cloned repository on the Github website and look on the right.

Click the icon next to the text field to copy the URL to your clipboard.

Return to your terminal window in your local development environment. Change to the directory that you wish to clone your repository in, and use the ‘git clone’ command to clone the repository, replacing ‘your-username’ with your Github username.

$ git clone git@github.com:your-username/ojs.git my-ojs-clone

The example above uses ‘git@’ URLs to clone the repositories, but these URLs do depend on having your command line environment configured to use SSH keys. Github supports several different styles of URLs, and if you encounter errors when running the above command, you should consult the informative help section on the Github website for further guidance, at https://help.github.com/articles/which-remote-url-should-i-use.

If you wish to use ‘git@’ URLs and you’d like more information in configuring SSH keys, please read the SSH help section on the Github website.

Configure the PKP-lib Sub-modules

We are almost ready to begin work. At this point, we must now configure the sub-modules for the PKP-lib repository. All you have to do is the following one-liner to recursively initialize and update all submodules:

git submodule update --init --recursive

All done!

Checking out the branch you want to work on

If all you want to work on is the "master" branch of the application you just checked out, you are ready to go at this point. If you are working on a stable branch of the software (for example OJS 2.4.x, or OCS 2.3.x) you will want to checkout a new branch based on the stable branch of that software. For OJS the command would be:

git checkout -b analytics origin/ojs-stable-2_4

This would create a new "analytics" branch in your local repo (named as such because you are presumably working on some analytics code - the name of the branch can be whatever you want). When you push this up to your remote repository, this branch and its committed code will be pushed up and available to submit a pull request from.

Contributing your work back to PKP

At this point, you are free to make changes to the code present in either of the two repositories that you have cloned into your local development environment. Since both of these repositories point to your own forks on Github, you can safely work knowing that your code will not affect the official repositories.

As you work, git provides several useful commands to track your progress. Since you are working off of your own forked repository, you can be relatively certain that there will be no upstream changes when you are ready to commit (unless you are sharing your repository with another collaborator). The typical lifecycle for a change may look like this:

Use the ‘git status’ command to see what files have been modified (or added) to a repository. Since you have two repositories (OJS and PKP-lib), this command will have to be run in both the OJS directory, and in the lib/pkp directory. Running this command may produce the following, if a single file has been changed.

As you can see, there are two modified files. The first one, .gitmodules, is marked as modified because we had to make a change to it in order to point it to our correct sub-module. This can be ignored. The second file, “templates/common/header.tpl”, contains a trivial modification. We can see this modification using the ‘git diff’ command.

Git will mark changed lines with either ‘+’ or ‘-’, to indicate whether they have been added or removed. It will also include some other lines around the changed ones to provide you with a bit of context. By default, git will not show changed lines in different colors, but if you would like this to be the case you can run the following command:

$ git config --global --add color.ui true

Committing your changes to your repository

If you are finished with your modifications at this point, you may commit them to your forked repository. Once they are committed, you may use Github’s ‘pull request’ feature to let the PKP development team that you have modifications that you’d like them to review.

To commit your changes, use the ‘git add’ command.

$ git add templates/common/header.tpl

You may use wildcards or directory paths if you wish to add many files at once. Once this is done, confirm that things have been added by re-running the ‘git status’ command.

The important part of the status message is in bold. It indicates that you have pushed your changes to your own fork of the OJS repository, to the master branch. At this point, if you view your forked repository on github, you will see the new commit.

Sending a Pull Request to PKP

At this point, the work is essentially finished. Had there also been changes made to the pkp-lib repository, the process would have been the same, except that the commands would have been run inside of the lib/pkp directory.

If you wish to submit your modifications, to PKP for review, you must now create a pull request. To do this, click on “pull requests” to the right of your forked repository page in Github.

This will load a new screen containing all of the pull requests for your project. Click the green “New Pull Request” button on the right to begin the process.

The next screen will contain detailed information about your current commit, and will include a link that can be clicked to initiate the request. Click the link.

At this point, you are finished. The PKP team will receive a notification that you have submitted a pull request. They will review your modifications, and possibly comment on your work, request small revisions, or merge it into the main PKP repositories outright.

Keeping your fork in sync with PKP

Github has become very good at automatically merging pull requests if it is possible. However, since you are not working in a vacuum and the PKP development team is continuing to contribute to the original fork, you may periodically want to pull any recent changes made to the official repositories into your own forked repository. This is done by creating a new ‘remote’ on your local development environment which is set up to point to the original PKP repository. You can then periodically fetch new commits from this remote and merge them into your local fork. Please be careful when doing this, since there may be occasions when changes made to the official repository will conflict with changes you have made to your own fork. An example of this would be when both repositories have changes made to the same file. Conflicts like this will need to be manually merged.

To set up a remote which tracks the official PKP repository, again using OJS as an example, please type the following command.

This indicates that there are two remotes, one called origin and the other called upstream. The former is your own fork since it points to your own account on Github. The latter, which only has fetch access, points to PKP’s OJS repository.

To sync changes made to the official repository into your own fork, you must first fetch the upstream repository with:

It is possible that much more content will be displayed if your own fork is significantly out of date. If you have local changes that may affect the merge process, you can ‘stash’ them before doing the merge, by running the following command right after you change to your own master branch:

$ git stash

You may re-apply your changes to the updated fork by running the following command *after* the merge is complete:

$ git stash apply

Again, be aware that if the the merge has significantly changed content in the repository, your stashed changes may not re-apply cleanly. In such instances, git will provide you with suggestions for resolving these conflicts.