kotovalexarian-likes-github
/
puma--puma
mirror of https://github.com/puma/puma.git
1
0
Fork 0
Code Releases Activity
puma--puma/CONTRIBUTING.md

189 lines
6.9 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-16 03:35:23 +00: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
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
There are lots of ways to contribute to Puma. Some examples include:
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-16 03:35:23 +00:00
* creating a [bug report] or [feature request]
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
* verifying [existing bug reports] and adding [reproduction steps]
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
* reviewing [pull requests] and testing the changes locally on your machine
Update CONTRIBUTING.md
2020-03-14 13:11:13 +00:00
* 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-16 03:35:23 +00:00
* improving test coverage
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00: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-16 03:35:23 +00: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-16 03:52:10 +00: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-16 03:35:23 +00:00
[pull requests]: https://github.com/puma/puma/pulls
Update CONTRIBUTING.md
2020-03-14 13:11:13 +00: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-16 03:35:23 +00:00
[reproduction steps]: https://github.com/puma/puma/blob/CONTRIBUTING.md#reproduction-steps
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00: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-16 03:35:23 +00:00
Newbies welcome
2020-03-14 13:12:36 +00: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-16 03:35:23 +00:00
## Setup
Close #2004
2020-10-21 20:40:34 +00:00
First step: join us on Matrix at [#puma-contrib:matrix.org](https://matrix.to/#/!blREBEDhVeXTYdjTVT:matrix.org?via=matrix.org)
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
Clone the Puma repository:
```sh
git clone git@github.com:puma/puma.git && cd puma
```
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
You 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-16 03:35:23 +00:00
macOS:
```sh
brew install ragel
```
Linux:
```sh
apt-get install ragel
```
Update CONTRIBUTING.md (#2612)
2021-04-26 01:23:23 +00:00
Windows (Ruby 2.5 and later):
```sh
ridk exec pacman -S mingw-w64-x86_64-openssl mingw-w64-x86_64-ragel
```
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
Install the Ruby dependencies:
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-16 03:35:23 +00:00
```sh
bundle install
```
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
To run Puma locally, you must compile the native extension.
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
Ubuntu, macOS, etc:
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
```sh
bundle exec rake compile
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
```
Update CONTRIBUTING.md (#2612)
2021-04-26 01:23:23 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
Windows:
```sh
Update CONTRIBUTING.md (#2612)
2021-04-26 01:23:23 +00:00
bundle exec rake -rdevkit compile
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
```
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
Now, you should be able to run Puma locally:
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
```sh
bundle exec bin/puma test/rackup/hello.ru
Update CONTRIBUTING.md (#2612)
2021-04-26 01:23:23 +00:00
# -or-
bundle exec ruby -Ilib bin/puma test/rackup/hello.ru
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
```
Adds instructions on referencing local gem to CONTRIBUTING (#2599) Resolves https://github.com/puma/puma/issues/2598
2021-04-17 14:28:51 +00: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.
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
[ragel]: https://www.colm.net/open-source/ragel/
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-16 03:35:23 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
## Running tests
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-16 03:35:23 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
To run the entire test suite:
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-16 03:35:23 +00:00
```sh
bundle exec rake test:all
```
To run a single test file:
```sh
Update CONTRIBUTING.md
2020-03-14 13:11:13 +00: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-16 03:35:23 +00:00
```
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
You can also run tests with [`m`](https://github.com/qrush/m):
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-16 03:35:23 +00:00
```sh
bundle exec m test/test_binder.rb
```
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
To run a single test:
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-16 03:35:23 +00:00
```sh
bundle exec m test/test_binder.rb:37
```
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
## How to contribute
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
Puma could use your help in several areas!
**The [contrib-wanted] label indicates that an issue might approachable to first-time contributors.**\
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
**Reproducing bug reports**: The [needs-repro] label indicates than an issue lacks reproduction steps. You can help by reproducing the issue and sharing the steps you took in the comments.
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
**Helping with our native extensions**: If you are interested in writing C or Java, we could really use your help. Check out the issue labels for [c-ext] and [JRuby].
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
**Fixing bugs**: Issues with the [bug] label have working reproduction steps, which you can use to write a test and submit a patch.
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
**Writing features**: The [feature] label highlights requests for new functionality. Write tests and code up our new feature!
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
**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!
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
**Write documentation**: Puma needs more docs in many areas, especially where we have open issues with the [docs] label.
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
[bug]: https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Abug
[c-ext]: https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Ac-ext
[contrib-wanted]: https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Acontrib-wanted
[docs]: https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Adocs
[feature]: https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Afeature
[jruby]: https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Ajruby
[needs-repro]: https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Aneeds-repro
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
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-16 03:35:23 +00:00
## Reproduction steps
Reproducing a bug helps identify the root cause of that bug so it can be fixed.
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
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-16 03:35:23 +00:00
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>
```
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
For example, using a test rack app ([`test/rackup/hello.ru`][rackup]) and a
test config file ([`test/config/settings.rb`][config]):
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-16 03:35:23 +00:00
```sh
bundle exec puma -C test/config/settings.rb test/rackup/hello.ru
```
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
There is also a Dockerfile available for reproducing Linux-specific issues:
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-16 03:35:23 +00:00
```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.
Update contributing.md [ci skip] (#2705) I'm making an effort to make the contributing document a bit more readable by decreasing redundant phrasing and adding a few links.
2021-09-21 15:58:09 +00:00
There's no need to update the changelog ([`History.md`](History.md)); that is done [when a new release is made](Release.md).
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
Update instructions for GitHub actions [ci skip] (#2717)
2021-09-29 18:03:25 +00:00
Puma uses [GitHub Actions](https://docs.github.com/en/actions) for CI testing. Please consider running the workflows in your fork before creating a PR. It is possible to enable GitHub Actions on your fork in the repositories' `Actions` tab.
Update CONTRIBUTING.md (#2612)
2021-04-26 01:23:23 +00:00
Introduce community backport policy
2020-11-14 22:01:55 +00:00
## Backports
Update CONTRIBUTING.md (#2612)
2021-04-26 01:23:23 +00: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 22:01:55 +00: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 20:40:34 +00: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-16 03:52:10 +00: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 13:11:13 +00:00
* [Puma's Architecture docs](https://github.com/puma/puma/blob/master/docs/architecture.md)
Updates Rack specification link (#2378)
2020-09-23 03:13:37 +00:00
* [The Rack specification](https://github.com/rack/rack/blob/master/SPEC.rdoc)
Add a few things to CONTRIBUTING
2019-10-16 03:52:10 +00:00
* The Ruby docs for IO.pipe, TCPServer/Socket.
* [nio4r documentation](https://github.com/socketry/nio4r/wiki/Getting-Started)