kotovalexarian-likes-github/puma--puma
1
0
Fork 0
mirror of https://github.com/puma/puma.git synced 2022-11-09 13:48:40 -05:00
Code Releases Activity
puma--puma/CONTRIBUTING.md

174 lines
6.1 KiB
Markdown
Raw Normal View History

Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
# Contributing to Puma
By participating in this project, you agree to follow the [code of conduct].
[code of conduct]: https://github.com/puma/puma/blob/master/CODE_OF_CONDUCT.md
There are lots of ways to contribute to puma. Some examples include:
* creating a [bug report] or [feature request]
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
* verifying [existing bug reports] and adding [reproduction steps]
Update CONTRIBUTING.md
2020-03-14 09:11:13 -04:00
* reviewing [pull requests] and testing the changes locally, on your own machine
* writing or editing [documentation]
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
* improving test coverage
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
* fixing a [reproducing bug] or adding a new feature
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
[bug report]: https://github.com/puma/puma/issues/new?template=bug_report.md
[feature request]: https://github.com/puma/puma/issues/new?template=feature_request.md
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
[existing bug reports]: https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Aneeds-repro
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
[pull requests]: https://github.com/puma/puma/pulls
Update CONTRIBUTING.md
2020-03-14 09:11:13 -04:00
[documentation]: https://github.com/puma/puma/tree/master/docs
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
[reproduction steps]: https://github.com/puma/puma/blob/CONTRIBUTING.md#reproduction-steps
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
[reproducing bug]: https://github.com/puma/puma/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Abug
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
Newbies welcome
2020-03-14 09:12:36 -04:00
Newbies welcome! We would be happy to help you make your first contribution to a F/OSS project.
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
## Setup
Close #2004
2020-10-21 16:40:34 -04:00
First step: join us on Matrix at [#puma-contrib:matrix.org](https://matrix.to/#/!blREBEDhVeXTYdjTVT:matrix.org?via=matrix.org)
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
Clone down the Puma repository.
Ragel 7 version note
2020-03-30 19:18:56 -04:00
You will need to install [ragel] (use Ragel version 7.0.0.9) to generate puma's extension code.
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
macOS:
```sh
brew install ragel
```
Linux:
```sh
apt-get install ragel
```
Install Ruby dependencies with:
```sh
bundle install
```
[ragel]: https://www.colm.net/open-source/ragel/
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
To run Puma, you will need to compile the native extension. To do this:
```sh
bundle exec rake compile
```
Then, you will be able to run Puma using your local copy with:
```sh
bundle exec bin/puma test/rackup/hello.ru
```
Adds instructions on referencing local gem to CONTRIBUTING (#2599) Resolves https://github.com/puma/puma/issues/2598
2021-04-17 10:28:51 -04:00
Alternatively, you can reference your local copy in a project's `Gemfile`:
```ruby
gem "puma", path: "/path/to/local/puma"
```
See the [Bundler docs](https://bundler.io/man/gemfile.5.html#PATH) for more details.
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
## Running tests
You can run the full test suite with:
```sh
bundle exec rake test:all
```
To run a single test file:
```sh
Update CONTRIBUTING.md
2020-03-14 09:11:13 -04:00
bundle exec ruby test/test_binder.rb
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
```
Or use [`m`](https://github.com/qrush/m):
```sh
bundle exec m test/test_binder.rb
```
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
... which can also be used to run a single test case:
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
```sh
bundle exec m test/test_binder.rb:37
```
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
## 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`.
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
## 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:
```sh
bundle exec puma -C <path/to/config.rb> <path/to/rackup.ru>
```
As an example, using one of the test rack apps:
Fix broken link [ci skip] [changelog skip] (#2445)
2020-10-22 20:08:16 -04:00
[`test/rackup/hello.ru`][rackup], and one of the test config files:
Add contribution guide [ci skip] (#2034) Closes #1880 As a recent first-time contributor to puma, there are some of the things that might have been helpful to have in one place as I worked on my first changes. I am also thinking about a resources section that links to the docs directory and to docs for libraries that might be unfamiliar to someone looking through puma for the first time (I didn't know much about TCPSocket, IO.pipe, nio4r, for example)
2019-10-15 23:35:23 -04:00
[`test/config/settings.rb`][config], you would run the test app with:
```sh
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:
```sh
docker build -f tools/docker/Dockerfile -t puma .
docker run -p 9292:9292 -it puma
```
[rackup]: https://github.com/puma/puma/blob/master/test/rackup/hello.ru
[config]: https://github.com/puma/puma/blob/master/test/config/settings.rb
## 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`](History.md)), add the text `[changelog skip]` to the
pull request title to skip [the changelog
check](https://github.com/puma/puma/pull/1991).
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
Introduce community backport policy
2020-11-14 17:01:55 -05:00
## Backports
Contributing typo [ci skip]
2020-11-14 17:02:37 -05:00
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`](SECURITY.md).
Introduce community backport policy
2020-11-14 17:01:55 -05:00
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.
Close #2004
2020-10-21 16:40:34 -04:00
## Join the community
If you're looking to contribute to Puma, please join us on Matrix at [#puma-contrib:matrix.org](https://matrix.to/#/!blREBEDhVeXTYdjTVT:matrix.org?via=matrix.org).
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
## 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:
Update CONTRIBUTING.md
2020-03-14 09:11:13 -04:00
* [Puma's Architecture docs](https://github.com/puma/puma/blob/master/docs/architecture.md)
Updates Rack specification link (#2378)
2020-09-22 23:13:37 -04:00
* [The Rack specification](https://github.com/rack/rack/blob/master/SPEC.rdoc)
Add a few things to CONTRIBUTING
2019-10-15 23:52:10 -04:00
* The Ruby docs for IO.pipe, TCPServer/Socket.
* [nio4r documentation](https://github.com/socketry/nio4r/wiki/Getting-Started)
Copy permalink