Skip to content

Latest commit

 

History

History
153 lines (102 loc) · 4.99 KB

CONTRIBUTING.md

File metadata and controls

153 lines (102 loc) · 4.99 KB
Raw

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:

Newbies welcome! We would be happy to help you make your first contribution to a F/OSS project.

Setup

Clone down the Puma repository.

You will need to install ragel (use Ragel version 7.0.0.9) 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:

bundle exec ruby 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][rackup file], 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: