Difference between revisions of "Information for Developers"

From PKP Wiki
Jump to: navigation, search
(General revisions/cleanup)
(Contributing via Github)
Line 13: Line 13:
== Contributing via Github ==
== Contributing via Github ==
Contributing code via Github is our '''preferred method'''. Please see http://pkp.sfu.ca/wiki/index.php/HOW-TO_check_out_PKP_applications_from_git and http://pkp.sfu.ca/wiki/index.php/Frequent_git_use_cases for extensive instructions on the ins and outs of working with git repositories.
Contributing code via Github is our '''preferred method'''. Please see [http://pkp.sfu.ca/wiki/index.php/HOW-TO_check_out_PKP_applications_from_git]. There are numerous excellent resources online for using git and github.
To contribute code back to us, feel free to submit a pull request from git.  
To contribute code back to us, feel free to submit a pull request from git.  

Revision as of 17:40, 9 January 2017

Managing Contributions

PKP code development, including external contributions, is managed in Github. We prefer that issues be opened as at Github issues for pkp-lib, and that fixes are submitted as pull requests via Github, but we do still accept patches sent to us directly if you do not want to submit via Github pull request.

Identifying an Issue

You can access our github.com-based issue tracker here. We welcome any bug reports and feature requests, so long as they are understandably written and as detailed as possible.

You are also advised to search for similar reports to avoid duplication.

Contributing Code

Contributing via Github

Contributing code via Github is our preferred method. Please see [1]. There are numerous excellent resources online for using git and github.

To contribute code back to us, feel free to submit a pull request from git.

If you are working against a particular entry in our issue database, use the following format for commit messages:

   pkp/pkp-lib#1234 My Commit Description

...where the 1234 is the issue number. This allows issues to track back to the commits made in that entry and helps us assemble release notes consistently.

PKP library submodule changes

Much of the OJS and OMP code is kept in a library shared by both applications, called pkp-lib. This is included in the OJS and OMP repositories as a git submodule, and packaged into the lib/pkp subdirectory when each application's release package is built.

If you need to change something in the pkp-lib shared library, you will also need to commit a submodule update in the application's repository (e.g. OJS or OMP). This is necessary especially for our continuous integration (CI) tools. Basically, when you commit a submodule update to the application's repository, it tells anyone checking out the application (including the continuous integration tools) that they should use the new version of the submodule including your changes.

If you're proposing changes to the pkp-lib shared library using your own fork, you'll need to use a specially formulated commit message proposing the submodule update. This is needed because the CI script by default will get the pkp-lib library from PKP's official repository, but you'll want it to use your fork of pkp-lib instead. That way the CI tool can check out, build and test your pull request code, including changes in pkp-lib. To make that happen, do the following:

  • create your commits normally, both for application and the pkp-lib library.
  • if you have commits in the pkp-lib library, commit the submodule change in the application repository, in a UNIQUE separate commit, making sure that it is the last commit:
git add lib/pkp
git commit -m 'pkp/pkp-lib#1234 Any message here ##githubUser/myBranch##'

...where 1234 is the git issue ID; githubUser is your github user; and myBranch is the branch in your github fork of pkpk-lib that contains the commits you want to test.

  • make sure your local application and library forks are up to date from the official repositories
  • push both pkp-lib library and application commits to your repository in github.

After doing this, you can create pull requests using the GitHub interface. This should automatically trigger the CI testing on the application repository so that you can check the CI build result. (The build process may take up to an hour.) If it doesn't pass, you can read the logs, see the errors, fix the code and update your pull request by pushing your code to your own repository again.

Contributing Patches

If you cannot or do not want to contribute via Github, you can upload patches directly to bug reports. We're always happy to receive patches, whether for contribution to a project or for general community availability on the forums. The one thing we do ask is that you provide the patch in Unified Diff format. If you are using our git instructions to work with the application codebase (highly recommended), you can create unified diffs via git using the following command:

git diff -u ./ > patch.diff

... which will find all differences in the working directory and recursively, and write them to a file called patch.diff.

Applying Patches

Patching Manually

If you want to apply a patch manually, download it to your development environment, and from the application's root directory and run

patch -p0 < ./path/to/patch.diff

The --dry-run option to the patch tool allows you to safely test the patch to see if it will apply cleanly, and if not, where the conflicts will arise.

For more Windows (and general) information, also see this forum thread.

Patching from Github

You can grab "patches" from Github by finding that particular commit's has and cherry-picking it:

First, find the hash for the commit you want to apply locally. The hash is the last string in the commit's URL, for example for the commit found at https://github.com/pkp/ojs/commit/4aba081d35133c1ee9a9e1f3b9166ca5db5fd48d it would be "4aba081d35133c1ee9a9e1f3b9166ca5db5fd48d".

Next, make sure your local repository is up to date (NB that this does not automatically merge all new remote commits to your repository, it just stores them locally):

git fetch 

Then, cherry-pick the commit you want to apply by hash:

git cherry-pick 4aba081d35133c1ee9a9e1f3b9166ca5db5fd48d

Setting up a flexible development environment

NB: This is not a beginner's installation/configuration tutorial. We only highlight a few important differences from a standard installation as a help for experienced PKP, database, PHP and web server users.

Install and Configure Databases

  • There is nothing special to the database installation. Use your OS' standard installation procedure to install the necessary databases you want to test in parallel.
  • Edit config.inc.php to switch the database connection.

Install and Configure supported PHP versions

  • Download or build the PHP binaries you want to test (newer versions can be downloaded from php.net or are part of the standard OS distributions, older versions must be built from source).
  • You'll need the thread-safe version if you want to test mod_php in Apache.
  • Install all binaries and configuration separately. Do not create any shared files or configuration (separate php.ini, separate installation directories).
  • On Windows:
    • Get the PHP zip arquive distributions where available and unzip them into separate folders.
    • XAMPP has lots of old Windows binaries if the version you look for is no longer officially supported on php.net.
    • Download the thread-safe VC6 version as VC9 versions are not compatible with Apache.
    • Do not install DLL files in C:\WINDOWS or any other directory on the path.
    • Do not install any registry keys.
    • Do not configure any shared environment variables.
  • Exception: Install PEAR in a central folder that is accessible by all PHP versions. Install necessary PEAR dependencies (e.g. PHPUnit, etc.) - see separate documentation on this Wiki for that.
  • Edit the development php.ini files as required:
    • extension_dir must point to the absolute path of the version specific extension binaries
    • enable extensions required by PKP software (e.g. database client, GD, etc.)
    • optional: error_reporting, display_errors, log_errors, error_log, max_execution_time, xdebug
  • Test all PHP installations separately: /path/to/php -c /path/to/php.ini -v (This should discover most problems with wrong extension paths).

Install and Configure Apache

We use Apache so that we can test CGI, FCGI and Module configurations in parallel. Install Apache 2.2 (standard distribution for your OS). Then get and install mod_fcgid as explained on the linked web pages.

All the magic lies in Apache's httpd.conf. Here's the Windows version. It should be easy to adapt that to your specific OS:

#General CGI Support
<IfDefine CGI>
    LoadModule cgi_module modules/mod_cgi.so
    AddHandler application/x-httpd-php .php
#General FCGI Support
<IfDefine FCGI>
    LoadModule fcgid_module modules/mod_fcgid.so
    AddHandler fcgid-script .php
    <Directory "C:/path/to/your/pkp/doc/root">
        Options +ExecCGI
#PHP 4.3 support
<IfDefine PHP43>
    <IfDefine CGI>
        Action application/x-httpd-php "/php-cgi/php.exe"
        ScriptAlias /php-cgi/ "C:/path/to/php43/"
        <Directory "C:/path/to/php43">
            Order allow,deny
            Allow from
#PHP 5.2 support
<IfDefine PHP52>
    <IfDefine MODULE>
        LoadFile "C:/path/to/php52/php5ts.dll"
        LoadFile "C:/path/to/php52/libmysql.dll" # This is required (PHP52 only) otherwise PHP might load libmysql.dll from MySQL's own bin
        LoadModule php5_module "C:/path/to/php52/php5apache2_2.dll"
        PHPIniDir "C:/path/to/php52"
    <IfDefine FCGI>
        FcgidWrapper "C:/path/to/php52/php-cgi.exe" .php
    <IfDefine CGI>
        Action application/x-httpd-php "/php-cgi/php-cgi.exe"
        ScriptAlias /php-cgi/ "C:/path/to/php52/"
        <Directory "C:/path/to/php52">
            Order allow,deny
            Allow from
#PHP 5.3 support
<IfDefine PHP53>
    <IfDefine MODULE>
        LoadFile "C:/path/to/php53/php5ts.dll"
        LoadModule php5_module "C:/path/to/php53/php5apache2_2.dll"
        PHPIniDir "C:/path/to/php53"
    <IfDefine FCGI>
        FcgidWrapper "C:/path/to/php53/php-cgi.exe" .php
    <IfDefine CGI>
        Action application/x-httpd-php "/php-cgi/php-cgi.exe"
        ScriptAlias /php-cgi/ "C:/path/to/php53/"
        <Directory "C:/path/to/php53">
            Order allow,deny
            Allow from
DocumentRoot "C:/path/to/your/pkp/doc/root"
<Directory "C:/path/to/your/pkp/doc/root">
    Options +FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all

Now all you need to switch configurations is starting Apache like this:


A few examples:

http -DPHP43 -DCGI
http -DPHP53 -DFCGI