4.7 KiB
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
Setup
Clone down the Puma repository.
You will need to install ragel to generate puma's extension code.
macOS:
brew install ragel
Linux:
apt-get install ragel
Install Ruby dependencies with:
bundle install
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
Running tests
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
Or use m:
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.
The 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 docs.
Reproduction steps
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>
As an example, using one of the test rack apps:
test/rackup/hello.ru, and one of the test config files:
test/config/settings.rb, you would run the test app with:
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
Pull requests
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.
If you open a pull request with a change that doesn't need to be noted in the
changelog (History.md), add the text [changelog skip] to the
pull request title to skip the changelog
check.
Bibliography/Reading
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:
- The Rack specification
- The Ruby docs for IO.pipe, TCPServer/Socket.
- nio4r documentation