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 main repository is hosted here. Lately, we've decided to switch to a new workflow in our process. Our two main branches are:
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.
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 email@example.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).
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.
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.
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!
This article has been written by Franck Cuny for the Perl Dancer Advent Calendar 2010.
Copyright (C) 2010 by franck cuny