Contributing to the Web and API components

Up and contributing in under 5 minutes

So what do you need to get started?

A computer! Once you've secured one of those all you need is a Github account. It helps to have a locally installed version of the frontend repository to test your changes. We've got lots of guides to help you get started. If you're updating any of the PHP code you should get PHPUnit as well.

pear channel-discover pear.phpunit.de
pear channel-discover pear.bovigo.org
pear install pear.phpunit.de/PHPUnit
pear install bovigo/vfsStream-beta

# problems? check the links below
# http://www.phpunit.de/manual/3.6/en/installation.html
# http://stackoverflow.com/questions/3301300/setting-up-phpunit-on-osx

Now that you've got:

A computer
A GitHub account
An installation of the frontend repository
PHPUnit,

let's continue.

Deciding what to fix

We've added a Beginner label to issues that don't touch some of the more sensitive parts of the code. We've additionally added CSS, JavaScript, and PHP labels so you can narrow it down to exactly what you're interested in.

Things to keep in mind while you code

Here are some guidelines for your code:

Unit tests should pass (more on that in the next section)
Spacing matters: two spaces, no tabs
Commits should reference an issue number (more on that below)
Comment your code so future developers can tell what's going on

Curly braces go on their own line. For example:

  if(condition)   
  {   
    statement 1;        
    statement 2;       
  }

  // or    
  if(condition)    
    only statement;

All in all, we recognize that everyone has a different style and level of experience, and we welcome all pull requests.

Testing that your change didn't break anything

Once you've made your change and verified it does what it should it's time to make sure it's not doing something it shouldn't. This is as easy as a single command.

phpunit -c src/tests/phpunit.xml
............................................................  60 / 311
............................................................ 120 / 311
............................................................ 180 / 311
...............I....................................I....... 240 / 311
........I......................I............................ 300 / 311
...........

Time: 2 seconds, Memory: 16.50Mb

OK, but incomplete or skipped tests!
Tests: 311, Assertions: 661, Incomplete: 4.

Those Is are okay but you shouldn't see any Es or Fs and definitely look for the OK message at the end. If all the tests pass then you're good to go and can commit your changes.

You can automate this by adding a pre-commit hook. Just copy this file into your .git/hooks directory or run the command below.

wget --no-check-certificate https://raw.github.com/photo/frontend/master/documentation/hooks/pre-commit -O .git/hooks/pre-commit
chmod u+x .git/hooks/pre-commit

Now every time you make a commit it will first run the unit tests automatically.

Committing your code

When committing your code it's important to reference the GitHub issue you're fixing. You can do it by adding a # followed by the issue number.

# To simply reference an issue with a commit do this
git commit -m 'Addressing the foobar component but not yet finished. #123'

# To commit and close an issue do this
git commit -m 'Fixing the most annoying bug ever. Closes #123'

Be descriptive, it helps a ton. Once you've committed your code it's time to push it to GitHub.

git push origin master

Getting your change into the OpenPhoto branch

To get your change merged into the official OpenPhoto branch, submit a pull request. GitHub's tutorial is better than anything we could do so we'll link to it.

It makes everyone's lives easier if you can remember to issue the pull request to OpenPhoto's development branch. If you forget, no big deal. The important thing is we get your change and your awesomeness can be merged into everyone else's awesomeness.

Help! I'm stuck and have questions

If you have questions we're always around to help. We've got several contact options listed on the contribute page.

5.2 KiB Raw Blame History