rubygems
/
puma
1
0
Fork 0
Code Packages Releases Activity
puma/CONTRIBUTING.md

239 lines
9.2 KiB
Markdown
Raw Permalink 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
Discussions + no claiming
2022-09-09 00:28:28 +00:00
Any questions about contributing may be asked in our [Discussions](https://github.com/puma/puma/discussions).
CONTRIBUTING: file limits [ci skip]
2022-01-24 17:50:01 +00:00
Re-add new contributor calls to CONTRIBUTING.md [ci skip]
2022-10-19 06:47:39 +00:00
**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](https://fantastical.app/nateberkopec/weekdays). He is happy to help!
CONTRIBUTING: file limits [ci skip]
2022-01-24 17:50:01 +00:00
#### Clone the repo
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
CONTRIBUTING: file limits [ci skip]
2022-01-24 17:50:01 +00:00
#### 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
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
```
Fix typo in CONTRIBUTING (#2805) [ci skip]
2022-01-25 10:40:46 +00:00
#### Install Ruby dependencies
CONTRIBUTING: file limits [ci skip]
2022-01-24 17:50:01 +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
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
```
CONTRIBUTING: file limits [ci skip]
2022-01-24 17:50:01 +00:00
#### Compile the native extensions
To run Puma locally, you must compile the native extension. Running the `test` rake task does this automatically, but you may need to manually run the compile command if you want to run Puma and haven't run the tests yet:
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
```
CONTRIBUTING: file limits [ci skip]
2022-01-24 17:50:01 +00:00
#### Run your local Puma
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
Removes debug info from tests by default (#2948) * Removes debug info from tests by default Much quieter/less confusing test output for newbies Keeps it on in CI * PUMA_DEBUG -> PUMA_TEST_DEBUG Co-authored-by: MSP-Greg <Greg.mpls@gmail.com>
2022-09-11 05:33:04 +00:00
To run rubocop + tests:
```sh
bundle exec rake
```
To run the test suite only:
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
Removes debug info from tests by default (#2948) * Removes debug info from tests by default Much quieter/less confusing test output for newbies Keeps it on in CI * PUMA_DEBUG -> PUMA_TEST_DEBUG Co-authored-by: MSP-Greg <Greg.mpls@gmail.com>
2022-09-11 05:33:04 +00:00
bundle exec rake 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
```
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
```
tests: add `TEST_CASE_TIMEOUT` (#2765) Useful if you want quicker feedback when you know something fails instantly, example: rerun -x -c -- TEST_CASE_TIMEOUT=2 bundle e m test/test_integration_ssl.rb:126
2021-12-11 21:59:49 +00:00
To run a single test with 5 seconds as the test case timeout:
```sh
TEST_CASE_TIMEOUT=5 bundle exec m test/test_binder.rb:37
```
Removes debug info from tests by default (#2948) * Removes debug info from tests by default Much quieter/less confusing test output for newbies Keeps it on in CI * PUMA_DEBUG -> PUMA_TEST_DEBUG Co-authored-by: MSP-Greg <Greg.mpls@gmail.com>
2022-09-11 05:33:04 +00:00
If you would like more information about extension building, SSL versions, your local Ruby version, and more, use the PUMA_TEST_DEBUG env variable:
```sh
PUMA_TEST_DEBUG=1 bundle exec rake test
```
CONTRIBUTING: file limits [ci skip]
2022-01-24 17:50:01 +00:00
#### File limits
Puma's test suite opens up a lot of sockets. This may exceed the default limit of your operating system. If your file limits are low, you may experience "too many open file" errors when running the Puma test suite.
```
CONTRIBUTING: spell out how to change ulimit (#2983) [ci skip]
2022-10-04 18:59:17 +00:00
# check your file limit
ulimit -S -n
# change file limit for the current session
ulimit -S -n <value>
CONTRIBUTING: file limits [ci skip]
2022-01-24 17:50:01 +00:00
```
We find that values of 4000 or more work well. [Learn more about your file limits and how to change them here.](https://wilsonmar.github.io/maximum-limits/)
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!
Contributing update [ci skip] Quick clarification on issue tracker
2022-10-28 05:09:43 +00:00
**Don't worry about "claiming an issue". No issues are "claimed" in Puma.** Just start working on it. The issue tracker is almost always kept updated, so if there is an open issue, it is ready for you to contribute (unless you have questions about how to close issue - then please ask!). Once you have a few lines of code, post a draft PR. We are more than happy to help once you have a draft PR up.
Discussions + no claiming
2022-09-09 00:28:28 +00:00
Update CONTRIBUTING.md
2022-09-21 05:34:27 +00:00
**New to systems programming? That's ok!** Puma deals with concepts you may not have been familiar with before, like sockets, TCP, UDP, SSL, and Threads. That's ok! You can learn by contributing. Also, see the "Bibliography" section at the end of this document.
Drop stray backslash in Markdown (#2815) [ci skip]
2022-01-30 11:13:42 +00:00
**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
Use Ruby 3.1 in our Dockerfile (#2802) Ruby 2.6 reaches EoL soon. [ci skip]
2022-01-17 21:47:16 +00:00
docker build -f tools/Dockerfile -t puma .
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
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
Discussions + no claiming
2022-09-09 00:28:28 +00:00
Please open draft PRs as soon as you are ready for feedback from the community.
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
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
Discussions + no claiming
2022-09-09 00:28:28 +00:00
If you're looking to contribute to Puma, please join us in [Discussions](https://github.com/puma/puma/discussions).
Close #2004
2020-10-21 20:40:34 +00:00
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)
Update CONTRIBUTING.md
2022-09-21 05:34:27 +00:00
* [Working with...](https://workingwithruby.com/) "Working With" is a excellent (and now free) Ruby book series about working with Threads, TCP and Unix Sockets.
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)