# Contributing to Concurrent Ruby

You want to contribute? Thank you! Concurrent Ruby is work of [many contributors](https://github.com/ruby-concurrency/concurrent-ruby/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/ruby-concurrency/concurrent-ruby/pulls), [propose features and discuss issues](https://github.com/ruby-concurrency/concurrent-ruby/issues). When in doubt, ask a question in the [Concurrent Ruby gitter.im chatroom](https://gitter.im/ruby-concurrency/concurrent-ruby) or on the [mailing list](https://groups.google.com/forum/#!forum/concurrent-ruby).

#### Find Something to Work on

If you want to contribute but aren't sure what to work on, we keep our list of current todos on our [issues page](https://github.com/ruby-concurrency/concurrent-ruby/issues). Before starting, feel free to chat with us on [gitter](https://gitter.im/ruby-concurrency/concurrent-ruby).

#### Fork the Project

Fork the [project on Github](https://github.com/ruby-concurrency/concurrent-ruby) and check out your copy.

```
git clone https://github.com/contributor/concurrent-ruby.git
cd concurrent-ruby
git remote add upstream https://github.com/ruby-concurrency/concurrent-ruby.git
```

#### Create a Topic Branch

Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.

```
git checkout master
git pull upstream master
git checkout -b my-feature-branch
```

#### Bundle Install, Buildn and Test


Ensure that you can build the project and run tests.

Please note that Concurrent Ruby includes native Java and (optional) C extensions. When building you will need the appropriate build tools for your platform. If you don't have the build tools installed that's OK. The tests can still be run. A few tests nay fail, but these are just the tests that verify that the extensions exist. You can usually ignore these locally if you are working on the pure Ruby parts of the library (which is most of the lib).

```
bundle install
bundle exec rake
```

#### Write Tests

Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [specs](https://github.com/ruby-concurrency/concurrent-ruby/tree/master/spec).

We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.

#### Write Code

Implement your feature or bug fix.

Make sure that `bundle exec rake` completes without errors.

#### Write Documentation

Document any external behavior in the [README](README.md).

#### Commit Changes

Make sure git knows your name and email address:

```
git config --global user.name "Your Name"
git config --global user.email "contributor@example.com"
```

Writing good commit logs is important. A commit log should describe what changed and why.

```
git add ...
git commit
```

#### Push

```
git push origin my-feature-branch
```

#### Make a Pull Request

Go to https://github.com/contributor/concurrent-ruby and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.

#### Rebase

If you've been working on a change for a while, rebase with upstream/master.

```
git fetch upstream
git rebase upstream/master
git push origin my-feature-branch -f
```

#### Update CHANGELOG Again

Update the [CHANGELOG](CHANGELOG.md) with a description of what you have changed.

Amend your previous commit and force push the changes.

```
git commit --amend
git push origin my-feature-branch -f
```

#### Check on Your Pull Request

Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI and AppVeyor. Everything should look green, otherwise fix issues and amend your commit as described above.

Please note that testing concurrency is hard. Very hard. We have a few tests that occasionally fail due (mostly) to incorrect synchronization within the test itself. If everything passes locally but you see an error on CI, it's possibly you've become victim to ont of the tests. Don't worry, the Concurrent Ruby team reviews the tests output of all failed CI runs and will let you know if the failing test is unrelated to your commit.

#### Thank You

Please do know that we really appreciate and value your time and work. We love you, really.

And also, a special thank you to the [Volt](https://github.com/voltrb/volt) team for writing an awesome guied for contributers. We have borroed liberally from theirs.
