Update contributing guidelines with more detailed info on filing bugs, editing the...

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fdd88f9f539f918e53444206a2a7949bc3dbc9fc..ba155717a7870372babb5a60a3c64d16b4f311a3 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,55 +1,53 @@
-# Foundation
+# Contributing to Foundation
 
-This is the Foundation project.  We love making super awesome stuff, but even more we like to empower people to make changes on their own.  Feel free to fork and improve Foundation.
+ZURB loves its community! We always want to hear from our users, whether they're reporting bugs, suggesting new features, or even adding them themselves.
 
-## Compass Project
+## Reporting Bugs
 
-If you have a compass project and would like updated assets you can run the following command at any given time from within your project directory:
+[Open a new issue](https://github.com/zurb/foundation-sites/issues/new) to report a problem you're having with Foundation for Apps. When writing your issue, keep these things in mind:
 
-```bash
-compass create -r zurb-foundation --using foundation
-```
+- **Be descriptive.** If you can, upload a screenshot of problem you're having, or copy and paste any JavaScript or command line errors you encounter. Being detailed will help us hone in on the problem faster.
+- **Post your code.** It's very helpful to see any HTML, Sass, or JavaScript you've written that you think may be causing the problem. In some cases, we might be able to fix your problem just by fixing your code.
+- **Help us recreate it.** If your problem is complex, tell us the steps needed to recreate the issue. Sometimes we need to see the problem for ourselves, in our own web browsers, so we can more easily debug it.
 
-## Development
+## Editing the Documentation
 
-Want to test out the Compass templates?  Don't recompile the gem every time, use `bundler` like so:
+The documentation is compiled by a tool called [Supercollider](https://github.com/gakimball/supercollider). Each page is compiled from 1–3 sources:
 
-```bash
-mkdir demo1
-cd demo1
-echo -e 'source "https://rubygems.org"\n
-gem "zurb-foundation", :path => "/path/to/foundation/repo"\n
-gem "compass"\n' > Gemfile
-bundle exec compass create -r zurb-foundation --using foundation
-```
+- A Markdown file under `docs/pages/`.
+- If it's a Sass component, the relevant Sass file inside `scss/` is scanned for special [SassDoc](http://sassdoc.com/) comments.
+- If it's a JavaScript component, the relevant JavaScript file inside `js/` is scanned for special [JSDoc](http://usejsdoc.org/) comments.
 
-On subsequent template updates use:
+Each page is rendered in one big [Handlebars template](https://github.com/zurb/foundation-docs/blob/master/templates/component.html) that takes in all of the above data.
 
-```bash
-bundle exec compass create -r zurb-foundation --using foundation --force
-```
+Much of the guts of the documentation are stored in an external codebase called [foundation-docs](https://github.com/zurb/foundation-docs). This is code that's shared between the documentation for all three Foundation frameworks, including:
 
-## Contributing
+- CSS specific to the documentation
+- The Handlebars template used to build pages
+- A series of Handlebars helpers for the template
+- A custom Markdown parser used when parsing pages
+- A script that generates the search results for documentation pages
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. All code should have a 2 space indentation to avoid conflicts.
-4. Test your changes to the best of your ability.
-5. Update the documentation to reflect your changes if they add or change current functionality. Instructions on how to view the documentation locally can be found in the [README](README.md#view-documentation-locally).
-6. Commit your changes (`git commit -am 'Added some feature'`)
-7. Push to the branch (`git push origin my-new-feature`)
-8. Create new Pull Request
+To hack on this repo locally, run the script `./docslink.sh` inside of the main Foundation repo. That will download foundation-docs and link it to your Foundation repo.
 
-## JavaScript Testing
+## Submitting Pull Requests
 
-The Foundation JS libraries are tested with Jasmine. Grunt can be used to run the test suite.
+If you think you can solve a problem yourself, or want to implement a new feature, go for it! Follow these guidelines to make the most killer PR ever.
 
-1. Install `node.js` and `npm` with `brew install node`
-    * You may need to `source` your bash config or restart your terminal client to make sure your PATH is up to date.
-2. From the root of the project, install required packages locally with `npm install`
-3. Install bower with `npm install -g bower` and and required assets locally `bower install`
-4. Install the command line interface for grunt with `npm install -g grunt-cli`
-5. Install PhantomJS with `brew install PhantomJS` (we assume you have Chrome and Firefox installed)
-    * If you get connection errors with PhantomJS when running the suite, ensure `node -v` returns  `v0.10.12` or later. Upgrade with `brew upgrade node`
-6. Run `grunt karma:dev` to run the tests with some real browsers
-7. Run `grunt build:assets` to compile any changes to foundation JS source into testing distribution
+- **Target the right branch.** So we can properly follow [semantic versioning](http://semver.org/), be sure to develop your pull request in the right branch:
+  - Documentation fixes: `master` (this allows us to deploy them to the live site right away)
+  - Bug fixes: `develop`
+  - New features `6.x` (we always have a public branch for the next minor version)
+  - Foundation 5 fixes: `V5`
+- **Test, test, and test.** The Foundation frameworks are used by thousands and thousands of designers and developers, so making sure your changes work in every browser is important! Foundation for Sites is officially supported on:
+  - Latest Chrome, Firefox, Safari, Edge, and Opera
+  - Internet Explorer 9+
+  - iOS 8+
+  - Android 2.3+
+
+## Help Wanted
+
+Want something to work on? Let us guide you in the right direction.
+
+- Browse the [Help Wanted](https://github.com/zurb/foundation-sites/labels/help%20wanted) issue to see bugs or features we've asked for the community's help on. Feel free to implement them yourself as a pull request!
+- Find the [roadmap](https://github.com/zurb/foundation-sites/issues/7759) for our next minor version to see what we've got planned. We always have an open issue, and a public branch, to see what we're working on for the next 6.x version.