Contributing to Puma
By participating in this project, you agree to follow the code of conduct.
There are lots of ways to contribute to puma. Some examples include:
- creating a bug report or feature request
- verifying existing bug reports and adding reproduction steps
- reviewing pull requests and testing the changes on your own machine
- writing or editing documentation
- improving test coverage
- fixing a reproducing bug or adding a new feature
Clone down the Puma repository.
You will need to install ragel to generate puma's extension code.
brew install ragel
apt-get install ragel
Install Ruby dependencies with:
To run Puma, you will need to compile the native extension. To do this:
bundle exec rake compile
Then, you will be able to run Puma using your local copy with:
bundle exec bin/puma test/rackup/hello.ru
You can run the full test suite with:
bundle exec rake test:all
To run a single test file:
ruby -Ilib test/test_binder.rb
bundle exec m test/test_binder.rb
... which can also be used to run a single test case:
bundle exec m test/test_binder.rb:37
How to contribute
Puma needs help in several areas.
contrib-wanted label is applied to issues that maintainers think would be easier for first-time contributors.
Reproducing bug reports: The
needs-repro label is applied to issues that have a bug report but no reproduction steps. You can help by trying to reproduce the issue and then posting how you did it.
Helping with our native extensions: If you can write C or Java, we could really use your help. Check out the issue labels for c-extensions and JRuby.
Fixing bugs: Issues with the
bug label have working reproduction steps, which you can use to write a test and create a patch.
Writing features: Issues with the
feature label are requests for new functionality. Write tests and code up our new feature!
Code review: Take a look at open pull requests and offer your feedback. Code review is not just for maintainers - we need your help and eyeballs!
Write documentation: Puma needs more docs in many areas, especially those where we have open issues labeled
Reproducing a bug helps identify the root cause of that bug so it can be fixed. To get started, create a rackup file and config file and then run your test app with:
bundle exec puma -C <path/to/config.rb> <path/to/rackup.ru>
bundle exec puma -C test/config/settings.rb test/rackup/hello.ru
There is also a Dockerfile available for reproducing Linux-specific issues. To use:
docker build -f tools/docker/Dockerfile -t puma . docker run -p 9292:9292 -it puma
Code contributions should generally include test coverage. If you aren't sure how to test your changes, please open a pull request and leave a comment asking for help.
Puma can be a bit intimidating for your first contribution because there's a lot of concepts here that you've probably never had to think about before - Rack, sockets, forking, threads etc. Here are some helpful links for learning more about things related to Puma: