first pass :dash: at breaking up documentation into good chunks

6 files changed, 184 insertions, 0 deletions

diff --git a/doc/contributing/BUG_TRIAGE.md b/doc/contributing/BUG_TRIAGE.md
new file mode 100644
index 0000000000..a8e9238369
--- /dev/null
+++ b/doc/contributing/BUG_TRIAGE.md
@@ -0,0 +1,38 @@
+# Bug triage
+
+Triage is the work of processing tickets that have been opened into actionable issues, feature requests, or bug reports. That includes verifying bugs, categorizing the ticket, and ensuring there's enough information to reproduce the bug for anyone who wants to try to fix it.
+
+We've created an [issues guide](ISSUES.md) to walk Bundler users through the process of troubleshooting issues and reporting bugs.
+
+If you'd like to help, awesome! You can [report a new bug](https://github.com/bundler/bundler/issues/new) or browse our [existing open tickets](https://github.com/bundler/bundler/issues).
+
+Not every ticket will point to a bug in Bundler's code, but open tickets usually mean that there is something we could improve to help that user. Sometimes that means writing additional documentation, sometimes that means making error messages clearer, and sometimes that means explaining to a user that they need to install git to use git gems.
+
+## Triaging existing issues
+
+When you're looking at a ticket, here are the main questions to ask:
+
+  * Can I reproduce this bug myself?
+  * Are the steps to reproduce clearly stated in the ticket?
+  * Which versions of Bundler (1.1.x, 1.2.x, git, etc.) manifest this bug?
+  * Which operating systems (OS X, Windows, Ubuntu, CentOS, etc.) manifest this bug?
+  * Which rubies (MRI, JRuby, Rubinius, etc.) and which versions (1.8.7, 1.9.3, etc.) have this bug?
+
+If you can't reproduce an issue, chances are good that the bug has been fixed (hurrah!). That's a good time to post to the ticket explaining what you did and how it worked.
+
+If you can reproduce an issue, you're well on your way to fixing it. :)
+
+## Fixing your triaged bug
+
+Fixing issues is similar to [adding new features](../development/NEW_FEATURES.md)!
+
+  1. Discuss the fix on the existing issue. Coordinating with everyone else saves duplicate work and serves as a great way to get suggestions and ideas if you need any.
+  2. Base your commits on the correct branch. Bugfixes for 1.x versions of Bundler should be based on the matching 1-x-stable branch.
+  3. Commit the code and at least one test covering your changes to a named branch in your fork.
+  4. Put a line in the [CHANGELOG](../../CHANGELOG.md) summarizing your changes under the next release under the “Bugfixes” heading.
+  5. Send us a [pull request](https://help.github.com/articles/using-pull-requests) from your bugfix branch.
+
+
+## Duplicates!
+
+Finally, the ticket may be a duplicate of another older ticket. If you notice a ticket is a duplicate, simply comment on the ticket noting the original ticket’s number. For example, you could say “This is a duplicate of issue #42, and can be closed”.
diff --git a/doc/contributing/COMMUNITY.md b/doc/contributing/COMMUNITY.md
new file mode 100644
index 0000000000..c25ef63eeb
--- /dev/null
+++ b/doc/contributing/COMMUNITY.md
@@ -0,0 +1,13 @@
+# Community
+
+Community is an important part of all we do. If you’d like to be part of the Bundler community, you can jump right in and start helping make Bundler better for everyone who uses it.
+
+It would be tremendously helpful to have more people answering questions about Bundler (and often simply about [Rubygems](https://github.com/rubygems/rubygems) or Ruby itself) in our [issue tracker](https://github.com/bundler/bundler/issues) or on [Stack Overflow](http://stackoverflow.com/questions/tagged/bundler).
+
+Additional documentation and explanation is always helpful, too. If you have any suggestions for the Bundler website [bundler.io](http://bundler.io), we would absolutely love it if you opened an issue or pull request on the [bundler-site](https://github.com/bundler/bundler-site) repository.
+
+Sharing your experiences and discoveries by writing them up is a valuable way to help others who have similar problems or experiences in the future. You can write a blog post, create an example and commit it to Github, take screenshots, or make videos.
+
+Publishing examples of how Bundler is used helps everyone, and we’ve discovered that people already use it in ways that we never imagined when we were writing it. If you’re still not sure what to write about, there are also several projects doing interesting things based on Bundler. They could probably use publicity too.
+
+Finally, all contributors to the Bundler project must agree to the contributor [code of conduct](http://bundler.io/conduct.html). By participating in this project you agree to abide by its terms.
diff --git a/doc/contributing/GETTING_HELP.md b/doc/contributing/GETTING_HELP.md
new file mode 100644
index 0000000000..55ccb5f5e9
--- /dev/null
+++ b/doc/contributing/GETTING_HELP.md
@@ -0,0 +1,11 @@
+# Getting help
+
+If you have any questions after reading the documentation for contributing, please feel free to contact either [@indirect](https://github.com/indirect), [@segiddins](https://github.com/segiddins), or [@RochesterinNYC](https://github.com/RochesterinNYC). They are all happy to provide help working through your first bug fix or thinking through the problem you’re trying to resolve.
+
+The best ways to get in touch are:
+
+* [Bundler Slack](https://bundler.slack.com).
+  * Not a member of the Slack? Join the Bundler team slack [here](http://slack.bundler.io/)!
+* [Bundler mailing list](http://groups.google.com/group/ruby-bundler)
+
+You may also find our guide on [filing issues](ISSUES.md) to be helpful as well!
diff --git a/doc/contributing/HOW_YOU_CAN_HELP.md b/doc/contributing/HOW_YOU_CAN_HELP.md
new file mode 100644
index 0000000000..b1e90de506
--- /dev/null
+++ b/doc/contributing/HOW_YOU_CAN_HELP.md
@@ -0,0 +1,27 @@
+# How you can help: your first commits!
+
+If you’re interested in contributing to Bundler, that’s awesome! We’d love your help.
+
+If at any point you get stuck, here's how to [get in touch with the Bundler team for help](GETTING_HELP.md).
+
+## First contribution suggestions
+
+We track [small bugs and features](https://github.com/bundler/bundler/labels/contribution%3A%20small) so that anyone who wants to help can start with something that's not too overwhelming.
+
+Generally, great ways to get started helping out with Bundler are:
+
+  - using prerelease versions (run `gem install bundler --pre`)
+  - [reporting bugs you encounter or suggesting new features](https://github.com/bundler/bundler/issues/new)
+    - see our [issues guide](ISSUES.md) for help on filing issues
+    - see the [new features documentation](../development/NEW_FEATURES.md) for more
+  - adding to or editing [the Bundler documentation website](http://bundler.io) and [Bundler man pages](http://bundler.io/man/bundle.1.html)
+  - [checking issues for completeness](BUG_TRIAGE.md)
+  - closing issues that are not complete
+  - adding a failing test for reproducible [reported bugs](https://github.com/bundler/bundler/issues)
+  - reviewing [pull requests](https://github.com/bundler/bundler/pulls) and suggesting improvements
+  - improving existing code, including suggestions from [PullReview](https://www.pullreview.com/github/bundler/bundler/reviews/master) or [CodeClimate](https://codeclimate.com/github/bundler/bundler)
+  - writing code (no patch is too small! fix typos or bad whitespace)
+    - get started setting up your dev environment with [these instructions](../development/DEVELOPMENT_SETUP.md)
+  - backfilling [unit tests](https://github.com/bundler/bundler/tree/master/spec/bundler) for modules that lack [coverage](https://codeclimate.com/github/bundler/bundler/coverage)
+
+If nothing on those lists looks good, [talk to us](http://slack.bundler.io/), and we'll figure out what you can help with. We can absolutely use your help, no matter what level of programming skill you have at the moment.
diff --git a/doc/contributing/ISSUES.md b/doc/contributing/ISSUES.md
new file mode 100644
index 0000000000..23a12330ed
--- /dev/null
+++ b/doc/contributing/ISSUES.md
@@ -0,0 +1,57 @@
+# Filing Issues: a guide
+
+So! You're having problems with Bundler. This file is here to help. If you're running into an error, try reading the rest of this file for help. If you can't figure out how to solve your problem, there are also instructions on how to report a bug.
+
+Before filing an issue, check our [troubleshooting guide](../TROUBLESHOOTING.md) for quick fixes to common issues.
+
+## Documentation
+
+Instructions for common Bundler uses can be found on the [Bundler documentation site](http://bundler.io/).
+
+Detailed information about each Bundler command, including help with common problems, can be found in the [Bundler man pages](http://bundler.io/man/bundle.1.html) or [Bundler Command Line Reference](http://bundler.io/v1.11/commands.html).
+
+## Reporting unresolved problems
+
+Check our [troubleshooting common issues guide](../TROUBLESHOOTING.md) and see if your issues is resolved using the steps provided.
+
+Hopefully the troubleshooting steps above resolved your problem! If things still aren't working the way you expect them to, please let us know so that we can diagnose and hopefully fix the problem you're having.
+
+**The best way to report a bug is by providing a reproduction script.** See these examples:
+
+* [Git environment variables causing install to fail.](https://gist.github.com/xaviershay/6207550)
+* [Multiple gems in a repository cannot be updated independently.](https://gist.github.com/xaviershay/6295889)
+
+A half working script with comments for the parts you were unable to automate is still appreciated.
+
+If you are unable to do that, please include the following information in your report:
+
+ - What you're trying to accomplish
+ - The command you ran
+ - What you expected to happen
+ - What actually happened
+ - The exception backtrace(s), if any
+ - Everything output by running `bundle env`
+
+If your version of Bundler does not have the `bundle env` command, then please include:
+
+ - Your `Gemfile`
+ - Your `Gemfile.lock`
+ - Your Bundler configuration settings (run `bundle config`)
+ - What version of bundler you are using (run `bundle -v`)
+ - What version of Ruby you are using (run `ruby -v`)
+ - What version of Rubygems you are using (run `gem -v`)
+ - Whether you are using RVM, and if so what version (run `rvm -v`)
+ - Whether you have the `rubygems-bundler` gem, which can break gem executables (run `gem list rubygems-bundler`)
+ - Whether you have the `open_gem` gem, which can cause rake activation conflicts (run `gem list open_gem`)
+
+If you are using Rails 2.3, please also include:
+
+  - Your `boot.rb` file
+  - Your `preinitializer.rb` file
+  - Your `environment.rb` file
+
+If you have either `rubygems-bundler` or `open_gem` installed, please try removing them and then following the troubleshooting steps above before opening a new ticket.
+
+[Create a gist](https://gist.github.com) containing all of that information, then visit the [Bundler issue tracker](https://github.com/bundler/bundler/issues) and [create a ticket](https://github.com/bundler/bundler/issues/new) describing your problem and linking to your gist.
+
+Thanks for reporting issues and helping make Bundler better!
diff --git a/doc/contributing/README.md b/doc/contributing/README.md
new file mode 100644
index 0000000000..29e6d9ddc5
--- /dev/null
+++ b/doc/contributing/README.md
@@ -0,0 +1,38 @@
+# Contributing to Bundler
+
+Welcome to Bundler! We are so happy that you're here. We know it can be daunting to joining a new open source project, so here's a quick overview of what you can expect from this documentation.
+
+*Something missing?* Send us a [pull request](../development/PULL_REQUESTS.md)!
+
+**Recommended first steps**
+
+- Join us in the Bundler slack! Generate an invite [here](http://slack.bundler.io/)
+- *If you're interested in helping with code:*
+  - Get a quick overview of our [development process](../development/README.md)
+  - [Setup your machine for development](../development/SETUP.md)
+  - Checkout [How you can help: your first contributions!](contributing/HOW_YOU_CAN_HELP.md) for a list of suggestions to get started
+- *If you're interested in helping with documentation:*
+  - Read up on [how documentation works for Bundler](../documentation/README.md)
+  - Learn about our [documentation vision](../documentation/VISION.md)
+
+You can start learning about Bundler by reading [the documentation](http://bundler.io). If you want, you can also read a (lengthy) explanation of [why Bundler exists and what it does](http://bundler.io/rationale.html).
+
+##[How you can help: your first contributions!](contributing/HOW_YOU_CAN_HELP.md)
+
+A detailed overview of how to get started contributing to Bundler, including a long list of suggestions for your first project.
+
+##[Bug triage](contributing/BUG_TRIAGE.md)
+
+Want to take a stab at processing issues? Start here.
+
+##[Getting help](contributing/GETTING_HELP.md)
+
+How to get in touch with folks who can help when you're stuck. Don't worry! This happens to all of us. We're really nice, we promise.
+
+##[Filing issues](contributing/ISSUES.md)
+
+We see a lot of issues in the Bundler repo! Use this guide to file informative, actionable issues.
+
+##[Community](contributing/COMMUNITY.md)
+
+Learn more about our goals for the Bundler community and the ways you can help us build better together.