How to contribute to Dancer

For our development projects, we rely a lot on Github. Lately, more and more people started contributing to Dancer (we've got nearly 40 contributors), but not all of them are familiar with Github or git. Here is a little step-by-step guide on how to contribute. You don't need to be a Perl expert to contribute, you can provide help by correcting documentation error, adding a new recipe to our cookbook, reporting bugs, adding tests, ...

The code

The main repository is hosted here. Lately, we've decided to switch to a new workflow in our process. Our two main branches are:

• master
• devel

The master branch is stable and should be in a state that allow a release at any time. The devel branch is used to our development.

Each new feature new to be created in a feature/$name_of_the_feature branch that will be merged into devel when it's done.

For this, we're using gitflow, waiting for our very own gitflux to be ready.

Contributing

First, go to github.com/sukria/dancer and click on the fork button. Now, here is a little tutorial on how to fetch the repository, list the local and remote branches, and track the remote devel branch.

$ git clone git@github.com:your_user/Dancer.git
Initialized empty Git repository in /tmp/Dancer/.git/
remote: Counting objects: 9299, done.
remote: Compressing objects: 100% (4236/4236), done.
remote: Total 9299 (delta 5740), reused 8015 (delta 4862)
Receiving objects: 100% (9299/9299), 1.20 MiB | 111 KiB/s, done.
Resolving deltas: 100% (5740/5740), done.

$ cd Dancer

$ git branch -l                                                                                                                                    
* master

$ git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/after_filter
remotes/origin/devel
remotes/origin/hooks
remotes/origin/master
remotes/origin/plack-middlewares
remotes/origin/psgi-refactor
remotes/origin/refactor/dtsimple-removal
remotes/origin/refactoring/app

$ git branch --track devel origin/devel

$ git branch -l
devel
* master

Now that you know what the purpose of each branch is, you can decide to work on master or devel (git checkout devel to switch branch).

Sending your patch

As I've previously stated, we rely a lot on the github features and interface. So now you've written your patch. First, be sure to provide one or more tests, and to run the test suite (with make test or prove -r t/). If all the tests pass, you can send a pull request. For this, you go on your own fork on github (http://github.com/$user/dancer), and you click on the Pull Request button.

You can at any time see all the commits done by others that have not yet been merged into one of our branches at this URL.

Reporting and/or fixing bugs

We prefer to use the github issue tracker instead of RT. So if you want to report a bug, go there|http://github.com/sukria/dancer/issues.

If your commit fixes a bug reported there, please add in your commit message something like 'closes gh-xxx" where xxx is the bug id.

Community work

There is nearly 40 different contributors to Dancer. There is a lot of plugins and engines available on CPAN and github. This is a real community effort. Thank you to everyone who have contributed so far!

Author

This article has been written by Franck Cuny for the Perl Dancer Advent Calendar 2010.

Copyright

Copyright (C) 2010 by franck cuny <franck@lumberjaph.net>