-
Notifications
You must be signed in to change notification settings - Fork 4
Contribute code to PKP
I want contribute code I've implemented in eschol_ojs back to the official pkp ojs repository (https://github.com/pkp/ojs). The following outlines the process for doing this.
Before I contribute my code, I want to make sure that it works against the official PKP code.
So I need to checkout OJS 2.4, for example, and test against it. Note: testing may not be necessary in your environment if you are in sync with the official PKP OJS repo. If this is you, then you can skip down to the "Tidy up your commit as necessary" section. Otherwise:
From within the ojs repository in a dev installation, list the current local branches:
$ git branch
If the version you want to switch to has already been checked out as a branch, great. Switch to it:
$ git checkout ojs-stable-2_4
If the version you want has not yet been checked out as a local branch, then do that now:
$ git branch -a # list all of the local and remote branches
$ git checkout -b ojs-stable-2_4 pkp-origin/ojs-stable-2_4 # for example
OK, so now you have checked out a given version of the OJS code.
In the superrepository (ojs):
$ git status
This will tell you that there are modifications in the lib/pkp submodule, because the current ojs expects the submodule to be at a particular commit, and the submodule is still at a commit that corresponds to the version we were on before we switched to 2.4. To figure out which commit git thinks the pkp-lib submodule should be at:
$ git submodule
This will show you something like the following:
-67542cad1b08517498911e6f651ab5e72f691dc8 lib/pkp
-31a1192887b7ff70a058ead1353f49be7246dccf plugins/importexport/duracloud/lib/DuraCloud-PHP
This tells me that for the current commit in ojs, there is a "pointer" registered for the 67542cad1b08 commit in the pkp-lib submodule. We want to make sure that pkp-lib is at that particular commit, otherwise it might not work with OJS.
$ cd lib/pkp
$ git checkout 67542cad1b08
$ cd ../..
$ git status
The discrepancy/change previously seen for lib/pkp should now be gone.
Find your fix and copy the (beginning of) the SHA1 hash for that commit.
You can find your SHA1 in a couple of different ways. The simplest is probably from within your repo on the command line. For example:
$ git branch
$ git checkout eschol_prod # checkout the branch where your change exists
$ git log # find the commit containing your change; copy the beginning of the SHA1
[...]
commit d234ad062e27acf947421c906ad5d08327d03c42
Author: Lisa Schiff <lisa.schiff@ucop.edu>
Date: Mon Jul 9 14:09:19 2012 -0700
[...]
Github is also pretty nice for finding commits. Either way, what you want is to find the SHA1 in question.
Now, apply the commit you just identified to your local ojs-stable-2_4 branch (see above for how to checkout a given version of the code into a local branch, if you haven't already).
$ git checkout ojs-stable-2_4
$ git cherry-pick d234ad062e27ac # you may have conflicts that need merging
Test to make sure things work.
As described here, PKP has certain naming conventions for commits that you should play nice and follow. In particular, include the Bugzilla # between asterisks in your commit message, e.g.:
*7984* Show archived items on author home pages
Use git commit --amend to make any changes, including modifying the message.
If there isn't an existing entry in PKP's Bugzilla, create one. For example: http://pkp.sfu.ca/bugzilla/show_bug.cgi?id=7984. Include a clear description of the issue and a link to any related forum posts.
We use Pivotal Tracker at CDL, so we also try to keep the commit message identical to the PT story name, and add the PKP Bugzilla # to PT as well.
Other general guidelines for getting your code ready to contribute:
- Get rid of any extraneous whitespace that may have been added inadvertently.
- Get rid of any extraneous comments that may not be useful to the larger community.
- (In general, declutter the commit and keep in line with PKP's coding conventions.)
Again, you can use git commit --amend to fix your commit. (Git has other powerful tools for wrangling your commit history as necessary, but let's not get into the details here.)
Of course, ideally you've already followed all of these conventions during development, but just in case :-)
Once you are satisfied with your commit, push it up to your account on github. You'll be issuing the pull request from there. (You could ostensibly do this without using github, but this seems easiest).
For example for the change described above:
$ git remote -v # check what you have configured as remotes (optional)
origin git@github.com:cdlib/eschol-ojs.git (fetch)
origin git@github.com:cdlib/eschol-ojs.git (push)
pkp_origin git@github.com:pkp/ojs.git (fetch)
pkp_origin git@github.com:pkp/ojs.git (push)
$ git push origin ojs-stable-2_4 # push the 'ojs-stable-2_4' branch to 'origin'
Point a browser to the repo you just pushed to on github. For this example, the URL is https://github.com/cdlib/eschol-ojs.
Make sure you're on the correct branch, i.e. the one in which the change you want to submit is located (in this case, ojs-stable-2_4). There's a branch dropdown menu just above your repo name, top left.
Navigate to the commit in question. You can get there by clicking the "commits" tab, which will show you a log of commits for that branch. Find your commit and click on it.
From the commit page, click on "Pull Request" at the top right. Select the relevant parameters. Provide a brief description for PKP.
Click on "Send Pull Request".
If your code was perfect, then it might be cheerfully accepted into the codebase. If not, you may get some feedback from PKP asking for changes before they will pull in your changes. If this is the case, then amend your commit using git commit --amend or another tool/method.
Then, once again, push the commit back up to your local github, navigate to the commit, and issue a pull request. [this gets tricky. filling in details on how to manage these changes. I think this is where we want to rebase our commits rather than merge in order to keep the history clean. Still need to think this through...]
Once PKP has merged in your commit, you'll get an email notification from github (if you have those set up, which I think is the default). Also, if you included the Bugzilla # in your commit message, then you should see a link to the commit appear in the Bugzilla entry.
To get back to the eschol_prod branch, cd into the ojs repository, and checkout the eschol_prod branch:
$ git checkout eschol_prod
Again, this should show a 'modification' in the lib/pkp submodule:
Checking out files: 100% (5853/5853), done.
M lib/pkp
Switched to branch 'eschol_prod'
So let's update the submodule to be on the right commit again:
$ git submodule
-ce55cf2e2a207e9d224e73b8526d6ad73fd34f1f lib/pkp
$ cd lib/pkp
$ git checkout ce55cf2e2a207
Previous HEAD position was 67542ca... *7725* Revert font changes for OJS 2.4.0
HEAD is now at ce55cf2... Adding journal initials
$ cd ../..
$ git status
# On branch eschol_prod
nothing to commit (working directory clean)