CONTRIBUTING.md

   1 Contributing to Rack
   2 =====================
   3
   4 Rack is work of [hundreds of contributors](https://github.com/rack/rack/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/rack/rack/pulls), [propose features and discuss issues](https://github.com/rack/rack/issues). When in doubt, post to the [rack-devel](http://groups.google.com/group/rack-devel) mailing list.
   5
   6 #### Fork the Project
   7
   8 Fork the [project on GitHub](https://github.com/rack/rack) and check out your copy.
   9
  10 ```
  11 git clone https://github.com/contributor/rack.git
  12 cd rack
  13 git remote add upstream https://github.com/rack/rack.git
  14 ```
  15
  16 #### Create a Topic Branch
  17
  18 Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
  19
  20 ```
  21 git checkout master
  22 git pull upstream master
  23 git checkout -b my-feature-branch
  24 ```
  25
  26 #### Bundle Install and Quick Test
  27
  28 Ensure that you can build the project and run quick tests.
  29
  30 ```
  31 bundle install --without extra
  32 bundle exec rake test
  33 ```
  34
  35 #### Running All Tests
  36
  37 Install all dependencies.
  38
  39 ```
  40 bundle install
  41 ```
  42
  43 Run all tests.
  44
  45 ```
  46 rake test
  47 ```
  48
  49 The test suite has no dependencies outside of the core Ruby installation and bacon.
  50
  51 Some tests will be skipped if a dependency is not found.
  52
  53 To run the test suite completely, you need:
  54
  55   * fcgi
  56   * dalli
  57   * thin
  58
  59 To test Memcache sessions, you need memcached (will be run on port 11211) and dalli installed.
  60
  61 #### Write Tests
  62
  63 Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build.
  64
  65 We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
  66
  67 #### Write Code
  68
  69 Implement your feature or bug fix.
  70
  71 Make sure that all tests pass:
  72
  73 ```
  74 bundle exec rake test
  75 ```
  76
  77 #### Write Documentation
  78
  79 Document any external behavior in the [README](README.rdoc).
  80
  81 #### Update Changelog
  82
  83 Add a line to [CHANGELOG](CHANGELOG.md).
  84
  85 #### Commit Changes
  86
  87 Make sure git knows your name and email address:
  88
  89 ```
  90 git config --global user.name "Your Name"
  91 git config --global user.email "contributor@example.com"
  92 ```
  93
  94 Writing good commit logs is important. A commit log should describe what changed and why.
  95
  96 ```
  97 git add ...
  98 git commit
  99 ```
 100
 101 #### Push
 102
 103 ```
 104 git push origin my-feature-branch
 105 ```
 106
 107 #### Make a Pull Request
 108
 109 Go to https://github.com/contributor/rack and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
 110
 111 #### Rebase
 112
 113 If you've been working on a change for a while, rebase with upstream/master.
 114
 115 ```
 116 git fetch upstream
 117 git rebase upstream/master
 118 git push origin my-feature-branch -f
 119 ```
 120
 121 #### Make Required Changes
 122
 123 Amend your previous commit and force push the changes.
 124
 125 ```
 126 git commit --amend
 127 git push origin my-feature-branch -f
 128 ```
 129
 130 #### Check on Your Pull Request
 131
 132 Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
 133
 134 #### Be Patient
 135
 136 It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
 137
 138 #### Thank You
 139
 140 Please do know that we really appreciate and value your time and work. We love you, really.