Skip to content

Latest commit

 

History

History
187 lines (122 loc) · 6.75 KB

CONTRIBUTING.md

File metadata and controls

187 lines (122 loc) · 6.75 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

First step: join us on Matrix at #puma-contrib:matrix.org

If you're nervous, get stuck, need help, or want to know where to start and where you can help, please don't hesitate to book 30 minutes with maintainer @nateberkopec here. He is happy to help!

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

Windows (Ruby 2.5 and later):

ridk exec pacman -S mingw-w64-x86_64-openssl mingw-w64-x86_64-ragel

Note: For all of the following commands you should be in your fork's directory.

Install Ruby dependencies with:

bundle install

To run Puma, you will need to compile the native extension. To do this:

# Ubuntu, macOS, etc
bundle exec rake compile

# Windows
bundle exec rake -rdevkit compile

Then, you will be able to run Puma using your local copy with:

bundle exec bin/puma test/rackup/hello.ru
# -or-
bundle exec ruby -Ilib bin/puma test/rackup/hello.ru

Alternatively, you can reference your local copy in a project's Gemfile:

gem "puma", path: "/path/to/local/puma"

See the Bundler docs for more details.

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, 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.

There's no need to update the changelog (History.md), as that is done when a new release is made.

Puma uses GitHub Actions for it's main CI testing. Please consider running the CI in your fork before creating a PR. A new repo (including forks) has Actions disabled. It can be set from the 'Settings' tab on your repo's web page.

Backports

Puma does not have a backport "policy" - maintainers will not consistently backport bugfixes to previous minor or major versions (we do treat security differently, see SECURITY.md.

As a contributor, you may make pull requests against -stable branches to backport fixes, and maintainers will release them once they're merged. For example, if you'd like to make a backport for 4.3.x, you can make a pull request against 4-3-stable. If there is no appropriate branch for the release you'd like to backport against, please just open an issue and we'll make one for you.

Join the community

If you're looking to contribute to Puma, please join us on Matrix at #puma-contrib:matrix.org.

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: