DP Code Development
Interested in helping out with the code behind pgdp.net? You've come to the right place!
Ways to get involved
There are numerous ways to get involved with the DP code, including:
- Coding - Compared to the pool of Proofers and Foofers on pgdp.net, the number of coders is very small. We're always looking for people who are interested in getting involved. While some of the parts of the system are rather complex there are many areas that folks can get their feet wet.
- Layout design - If you have HTML layout and/or CSS design experience but not any coding experience we can use your help too! As of this writing, most of our developers are stronger coders than they are website designers and we could use help with some head-scratching design questions.
- Documentation - We could use help with both documenting how the current system works. The code has grown organically over the past several years and there are some "here be dragon" areas of the code. Having some documentation on how these areas work would be a big help. This would likely require talking with existing developers and rummaging through code but little, if any, actual programming.
- Testing - Developers are the ones in charge of testing their own code. Often it is helpful for others to test the changes as well to ensure there are no browser issues or general confusion surrounding the code changes.
To jump in and get started:
- Drop into one of the developer discussion rooms to see who's around and say hello (see #Communicating for details).
- Look at the Task Center or DP Code Wishlist for a bug or feature you'd like to work on.
- It's a good idea to discuss what you'd like to work on with developers in the discussion rooms (Slack and/or Jabber) or mailing list so they can advise you if There Be Dragons.
- Create an account on GitHub (or log in to an existing one).
- Fork the DP code repository and clone the code to your workstation or a DP development VM using instructions on DP Code Development Using git.
- Look around, create a few branches, commit some code to your repository, and get familiar with the code base. Again, see #Communicating.
- When you're ready to demo your code to other developers or volunteers, request a sandbox on the Test server.
More details on these steps are below.
The source code that drives pgdp.net is Open Source software under the GPL license. It is currently hosted on GitHub under the Distributed Proofreaders organization. The code is written in PHP, a web-centric interpreted language. If you've ever done any Perl, python, or C coding you'll find PHP very familiar. Syntactically, PHP resembles C, so C programmers will have a smaller learning curve than would, say, a COBOL programmer :)
Other sites beyond www.pgdp.net use the DP source code, including most of our sister sites like DP Canada and DP Europe.
DP code is stored in a git repository on GitHub. As there are multiple ways to use git to manage source code, please see DP Code Development Using git for how DP is using it and how to use it to contribute changes.
To simply clone the main repository, however, use:
git clone https://github.com/DistributedProofreaders/dproofreaders.git
Supported middleware versions
When developing, keep in mind the middleware versions we must support. SETUP/installation.txt has the full list and is authoritative.
- PHP version 7.0 is supported. 7.1 and later should work but have not been tested.
- MySQL version 5.5 and later is recommended. Versions 5.1 and later may work but are untested.
- MariaDB version 5.5 and later should also work but has not been tested.
- phpBB 3.1 and 3.2 are supported. Version 3.2 is recommended.
- jpgraph versions 3.5.0b1, 4.0.2, 4.1.0, and 4.2.0 will work after applying the included patches (4.0.2 patch will work with 4.1.0 and 4.2.0). Version 4.2.0 is recommended.
These middleware components match the following major distribution releases:
- Ubuntu 12.04, Precise
- Ubuntu 14.04, Trusty
- Ubuntu 16.04, Xenial
- RHEL / CentOS 6.x family
- RHEL / CentOS 7.x family
Coding conventions and best practices
This is detailed in a separate page.
Interested developers can request a system account on the DP Test server, www.pgdp.org. This allows users a location to test out new code and get feedback from other developers and DP users. Accounts on this server share a common database but have separate code bases. Send an email to the DP General Manager to request a sandbox on the Test server. If approved, one of the squirrels will reach out to you when setting it up to get your public key.
Anyone can download a development VM to develop against on their local workstation.
Defect & Feature tracking
We use the Task Center to track DP defects and features.
Use it to document what you are working on and the progress you are making. If you wish to start working on a problem/feature, check the Task Center to see if there is an existing Task which is related to or covers what you wish to work on. If there is, and it hasn't been assigned to anyone, assign it to yourself. If there isn't an existing Task, please create one.
Be aware that, if a task is a Feature Request, it isn't necessarily a feature that lots of people want. In fact, many people might actively not want it. If you think a feature might be controversial or unpopular, feel free to discuss it on the developers' list.
The DP Code Wishlist has some big-picture ideas as well.
As of Jan 2016, DP developers use Slack for communicating. Unlike Jabber, it has the bonus of persisting logs even when you're not connected and can be accessed from a web browser as well as mobile apps. You must be invited to join the slack team. To get added, send cpeel a PM to introduce yourself and how you'd like to help with the DP code development.
Before you start working on a change, be sure to sync your fork from to the upstream DP git repo. Develop your code on a new git branch (per the instructions in DP Code Development Using git) either on your home system or on the Test server. When committing code to your branch, please add any relevant Task Center task IDs (e.g., "Fixed off-by-one error in 'your neighborhood'. (task #333)", or "Implements project-filtering feature requested in task #456.").
Regardless of where you do your development, you should test changes in a "sandbox" on the test server. If you do not have a sandbox set up on the test server and would like one, please send a request to the Site Admins. An account will be created for you and information provided to help you through the remaining setup. Note that, so far, these are only code sandboxes: personal copies of the site code. They do not give you complete isolation, in that they (and the test site) share a single database and a single projects hierarchy. So be careful.
It's a good idea to get other people to test your code while it's still in your git branch (not yet merged up to the master repo). Announce your changes to the developers' mailing list, including a list of modified files, a description of the changed functionality, and a link into your sandbox. (If your changes address a task in the Task Center, it would be handy to include a link to that too.) Jabberwockies in the general DP chat room are often good test subjects. Make sure they understand what specifically needs testing.
Once testing is done, open a merge request back to the master repo. This should notify other DP developers about your code, but it may be worthwhile to send an email to the development mailing list as well.
After the merge is accepted, but before it is nominated to production, contact the Site Admins to have your code installed to the test site. A Site Admin will make your changes visible at http://www.pgdp.org/c as time permits. This is a good time to call for more thorough testing of the change in the DP Forums if needed. If problems arise during testing in the test site, hopefully you can fix them quickly. If not, we can back out your changes on the test site, and you can continue to work on the fix in your sandbox/home system.
Once your change is working on the test site, please mark any associated tasks in the Task Center as implemented or fixed. However, leave them open and at 90% progress until the change is visible on the live site.
If your change warrants immediate installation on the production site, contact a Site Admin, and they can make your change visible to the DP community. The associated tasks can then be closed in the Task Center.