2014-12-19 07:55:40 -05:00
|
|
|
# Contributing to Ransack
|
|
|
|
|
|
|
|
Please take a moment to review this document in order to make the contribution
|
|
|
|
process easy and effective for everyone involved!
|
|
|
|
|
2012-11-28 23:52:50 -05:00
|
|
|
Ransack is an open source project and we encourage contributions.
|
|
|
|
|
|
|
|
## Filing an issue
|
|
|
|
|
2014-12-19 07:55:40 -05:00
|
|
|
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
2015-01-09 08:44:49 -05:00
|
|
|
Good bug reports are extremely helpful! Please do not use the issue tracker for personal support requests.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2014-12-19 07:55:40 -05:00
|
|
|
Guidelines for bug reports:
|
|
|
|
|
|
|
|
1. **Use the GitHub issue search** — check if the issue has already been
|
|
|
|
reported.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2014-12-19 07:55:40 -05:00
|
|
|
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
|
|
`master` branch in the repository.
|
|
|
|
|
|
|
|
3. **Isolate and report the problem** — ideally create a reduced test
|
|
|
|
case.
|
|
|
|
|
|
|
|
When filing an issue, please provide these details:
|
|
|
|
|
|
|
|
* A comprehensive list of steps to reproduce the issue, or - far better - **a failing spec**.
|
|
|
|
* The version (and branch) of Ransack *and* the versions of Rails, Ruby, and your operating system.
|
|
|
|
* Any relevant stack traces ("Full trace" preferred).
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2013-12-06 19:51:55 -05:00
|
|
|
Any issue that is open for 14 days without actionable information or activity
|
|
|
|
will be marked as "stalled" and then closed. Stalled issues can be re-opened
|
|
|
|
if the information requested is provided.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
|
|
|
## Pull requests
|
|
|
|
|
2013-12-06 19:51:55 -05:00
|
|
|
We gladly accept pull requests to fix bugs and, in some circumstances, add new
|
|
|
|
features to Ransack.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2015-01-11 17:12:44 -05:00
|
|
|
If you're new to contributing to open source, welcome! It can seem scary, so
|
|
|
|
here is a [great blog post to help you get started]
|
|
|
|
(http://robots.thoughtbot.com/8-new-steps-for-fixing-other-peoples-code),
|
|
|
|
step by step.
|
|
|
|
|
2014-05-06 04:59:42 -04:00
|
|
|
Before issuing a pull request, please make sure that all specs are passing,
|
|
|
|
that any new features have test coverage, and that anything that breaks
|
|
|
|
backward compatibility has a very good reason for doing so.
|
|
|
|
|
2012-11-28 23:52:50 -05:00
|
|
|
Here's a quick guide:
|
|
|
|
|
2015-01-09 08:44:49 -05:00
|
|
|
1. Fork the repo, clone it, create a thoughtfully-named branch for your changes,
|
|
|
|
and install the development dependencies by running `bundle install`.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2015-01-09 08:44:49 -05:00
|
|
|
2. Begin by running the tests. We only take pull requests with passing tests,
|
|
|
|
and it's great to know that you have a clean slate:
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2013-12-06 19:51:55 -05:00
|
|
|
$ bundle exec rake spec
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2015-01-09 08:44:49 -05:00
|
|
|
3. Hack away! Please use Ruby features that are compatible down to Ruby 1.9.
|
|
|
|
Since version 1.5, Ransack no longer maintains Ruby 1.8 compatibility.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2015-01-09 08:44:49 -05:00
|
|
|
4. Add tests for your changes. Only refactoring and documentation changes
|
|
|
|
require no new tests. If you are adding functionality or fixing a bug, we
|
|
|
|
need a test!
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2015-01-09 08:44:49 -05:00
|
|
|
5. Make the tests pass.
|
2014-12-17 18:17:22 -05:00
|
|
|
|
2015-01-09 08:44:49 -05:00
|
|
|
6. Update the Change Log. If you are adding new functionality, document it in
|
|
|
|
the README.
|
|
|
|
|
|
|
|
7. Do not change the version number; we will do that on our end.
|
|
|
|
|
|
|
|
8. If necessary, rebase your commits into logical chunks, without errors.
|
|
|
|
|
|
|
|
9. Push the branch up to your fork on Github and submit a pull request. If the
|
|
|
|
changes will apply cleanly to the latest stable branches and master branch,
|
|
|
|
you will only need to submit one pull request.
|
|
|
|
|
|
|
|
10. If your pull request only contains documentation changes, please remember to
|
|
|
|
add `[skip ci]` to your commit message so the Travis test suite doesn't run
|
|
|
|
needlessly.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
|
|
|
At this point you're waiting on us. We like to at least comment on, if not
|
|
|
|
accept, pull requests within three business days (and, typically, one business
|
|
|
|
day). We may suggest some changes or improvements or alternatives.
|
|
|
|
|
2015-01-09 08:44:49 -05:00
|
|
|
Some things that will increase the chance that your pull request is accepted:
|
2012-11-28 23:52:50 -05:00
|
|
|
|
2015-01-09 08:44:49 -05:00
|
|
|
* Use idiomatic Ruby and follow the syntax conventions below.
|
2014-10-14 16:02:18 -04:00
|
|
|
* Include tests that fail without your code, and pass with it.
|
|
|
|
* Update the README, the change log, the wiki documentation... anything that is
|
|
|
|
affected by your contribution.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
|
|
|
Syntax:
|
|
|
|
|
|
|
|
* Two spaces, no tabs.
|
2014-05-06 04:59:42 -04:00
|
|
|
* 80 characters per line.
|
2012-11-28 23:52:50 -05:00
|
|
|
* No trailing whitespace. Blank lines should not have any space.
|
2014-10-14 16:02:18 -04:00
|
|
|
* Prefer `&&`/`||` over `and`/`or`.
|
2012-11-28 23:52:50 -05:00
|
|
|
* `MyClass.my_method(my_arg)` not `my_method( my_arg )` or my_method my_arg.
|
|
|
|
* `a = b` and not `a=b`.
|
2014-05-06 04:59:42 -04:00
|
|
|
* `a_method { |block| ... }` and not `a_method { | block | ... }` or
|
|
|
|
`a_method{|block| ...}`.
|
2015-01-09 08:44:49 -05:00
|
|
|
* Prefer simplicity, readability, and maintainability over terseness.
|
|
|
|
* Follow the conventions you see used in the code already.
|
2012-11-28 23:52:50 -05:00
|
|
|
|
|
|
|
And in case we didn't emphasize it enough: we love tests!
|