From c38d61cf67cc73af928cb7f1fe77860817ccc997 Mon Sep 17 00:00:00 2001
From: Nate Berkopec <nate.berkopec@gmail.com>
Date: Mon, 24 Jan 2022 10:50:01 -0700
Subject: [PATCH] CONTRIBUTING: file limits

[ci skip]
---
 CONTRIBUTING.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ca2cca5745..cd2f1d7b5e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,11 +27,16 @@ Newbies welcome! We would be happy to help you make your first contribution to a
 
 First step: join us on Matrix at [#puma-contrib:matrix.org](https://matrix.to/#/!blREBEDhVeXTYdjTVT:matrix.org?via=matrix.org)
 
+
+#### Clone the repo 
+
 Clone the Puma repository:
 ```sh
 git clone git@github.com:puma/puma.git && cd puma
 ```
 
+#### Ragel
+
 You need to install [ragel] (use Ragel version 7.0.0.9) to generate Puma's extension code.
 
 macOS:
@@ -50,12 +55,16 @@ Windows (Ruby 2.5 and later):
 ridk exec pacman -S mingw-w64-x86_64-openssl mingw-w64-x86_64-ragel
 ```
 
+#### Install Ruby depedencies
+
 Install the Ruby dependencies:
 ```sh
 bundle install
 ```
 
-To run Puma locally, you must compile the native extension.
+#### 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:
 
 Ubuntu, macOS, etc:
 ```sh
@@ -67,6 +76,8 @@ Windows:
 bundle exec rake -rdevkit compile
 ```
 
+#### Run your local Puma
+
 Now, you should be able to run Puma locally:
 
 ```sh
@@ -112,6 +123,18 @@ To run a single test with 5 seconds as the test case timeout:
 TEST_CASE_TIMEOUT=5 bundle exec m test/test_binder.rb:37
 ```
 
+#### 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.
+
+Check your file limit:
+
+```
+ulimit -Sn
+```
+
+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/)
+
 ## How to contribute
 
 Puma could use your help in several areas!