Merge pull request #1166 from mathjax/hotfix-2.5.2

Merge v2.5.2 for release

CONTRIBUTING.md

@@ -1,20 +1,19 @@
 # Contributing to MathJax
 
-So you're interested in giving us a hand? That's awesome! We've put
-together some brief guidelines that should help you get started
-quickly and easily.
+You are interested in giving us a hand? That's awesome! We've put together some brief guidelines that should help you get started quickly and easily.
 
 There are lots and lots of ways to get involved, this document covers:
 
-* [raising issues](#raising-issues)
+* [reporting an issue](#reporting-an-issue)
     * [bug reports](#bug-reports)
     * [feature requests](#feature-requests)
     * [change requests](#change-requests)
-* [working on MathJax core](#working-on-MathJax-core)
+* [working on MathJax core](#working-on-mathjax-core)
+    * [key branches and tags](#key-branches--tags)
     * [submitting pull requests](#submitting-pull-requests)
-* [testing and quality assurance](#testing-and-quality-assurance)
-* [writing documentation](#writing-documentation)
-* [translation](#translation)
+    * [testing and quality assurance](#testing-and-quality-assurance)
+    * [writing documentation](#writing-documentation)
+    * [translation](#translation)
 * [Conduct](#conduct)
 
 
@@ -33,7 +32,7 @@ requests](#submitting-pull-requests), but please respect the following restricti
   problem or requested your idea.
 
 * Please **do not** use the issue tracker for personal support
-  requests (use [the MathJax User Group](https://groups.google.com/forum/#!forum/mathjax-users).
+  requests (use [the MathJax User Group](https://groups.google.com/forum/#!forum/mathjax-users)).
 
 * Please **be civil**. Keep the discussion on topic and respect the
   opinions of others. See also our [Conduct Guidelines](#conduct)
@@ -48,21 +47,19 @@ Guidelines for bug reports:
 1. **Use the GitHub issue search** — check if the issue has already been
    reported.
 
-2. **Check if the issue has been fixed** — try to reproduce it
-   using the latest `develop` or look for [closed issues in the
-   current milestone](https://github.com/MathJax/MathJax/issues?&page=1&state=closed).
+2. **Check if the issue has been fixed** — look for [closed issues in the
+   current milestone](https://github.com/MathJax/MathJax/issues?&page=1&state=closed) or try to reproduce it
+   using the latest `develop` branch. Please note that we only pack MathJax for releases, so on the `develop` branch you have to use `/unpacked/MathJax.js` etc. to test.
 
-3. **Isolate the problem** — ideally create a [reduced test
-   case](http://css-tricks.com/6263-reduced-test-cases/) and a live example.
+3. **Share a live sample of the problem** — without a live page it is usually impossible to debug problems; see also the Bug Report Template below.
 
-4. **Include a screencast if relevant** - Is your issue about a design
-   or front end feature or bug? The most helpful thing in the world is
-   if we can *see* what you're talking about. Use
-   [LICEcap](http://www.cockos.com/licecap/) to quickly and easily
-   record a short screencast (24fps) and save it as an animated gif!
-   Embed it directly into your GitHub issue. Kapow.
+4. **Isolate the problem** — a live sample is a starting point but if you want to speed things up create a [reduced test
+   case](http://css-tricks.com/6263-reduced-test-cases/). Be specific about your setup (browser, OS versions etc). Use services like [jsbin](http://jsbin.com), [CodePen](http://codepen.io), [JSfiddle](http://jsfiddle.com) to make collaboration on minimal test cases easier for everyone. Use the unpacked copy of MathJax (`[...]/unpacked/MathJax.js` etc.) for better debugging.
 
-5. Use the Bug Report template below or [click this
+5. **Include a screenshot/cast as a last resort** — Is your issue about a layout
+   or design feature / bug but hard to reproduce or isolate? Then please provide a screenshot or screencast. Tools like [LICEcap](http://www.cockos.com/licecap/) or [SauceLabs](http://www.saucelabs.com) allow you to quickly and easily record a screencasts. Make it an animated gif, embed it directly into your GitHub issue -- kapow!
+
+6. Use the Bug Report template below or [click this
    link](https://github.com/MathJax/MathJax/issues/new?title=Bug%3A&body=%23%23%23%20Issue%20Summary%0A%0A%23%23%23%20Steps%20to%20Reproduce%0A%0A1.%20This%20is%20the%20first%20step%0A%0AThis%20is%20a%20bug%20because...%0A%0A%23%23%23%20Technical%20details%0A%0A*%20MathJax%20Version%3A%20master%20-%20latest%20commit%3A%20%20INSERT%20COMMIT%20REF%0A*%20Client%20OS%3A%20%0A*%20Browser%3A%20%0A*%20)
    to start creating a bug report with the template automatically.
 
@@ -132,12 +129,27 @@ a refactor, or an improvement to a feature, etc - please be sure to:
    are suggesting better than what's already there? Does it fit with
    the Roadmap?
 
+## Working on MathJax core
+
+You want to contribute code? Fantastic! Let's get you started.
+
+### Key Branches & Tags
+
+To get it out of the way:
+
+- **[develop](https://github.com/MathJax/MathJax/tree/develop)** is
+  the development branch. All work on the next release happens here so
+  you should generally branch off `develop`. Do **NOT** use this branch
+  for a production site. 
+- **[master](https://github.com/MathJax/MathJax)** contains the latest
+  release of MathJax. This branch may be used in production. Do 
+  **NOT** use this branch to work on MathJax's source.
 
 ### Submitting Pull Requests
 
 Pull requests are awesome. If you're looking to raise a PR for
 something which doesn't have an open issue, please think carefully
-about [raising an issue](#raising-issues) which your PR can close,
+about [raising an issue](#reporting-an-issue) which your PR can close,
 especially if you're fixing a bug. This makes it more likely that
 there will be enough information available for your PR to be properly
 tested and merged.
@@ -165,7 +177,7 @@ Documentation [in our testing
 framework](https://github.com/MathJax/MathJax-testing).
 
 Essentially though, [check out the latest develop
-branch](#contribute-to-core), take it for a spin, and if you find
+branch](#working-on-mathJax-core), take it for a spin, and if you find
 anything odd, please follow the [bug report guidelines](#bug-reports)
 and let us know!
 
@@ -178,45 +190,31 @@ requests in the same way as branches:
 <https://gist.github.com/piscisaureus/3342247>.
 
 
-### Documentation
+### Writing documentation
 
 MathJax's main documentation can be found at [docs.mathjax.org](http://docs.mathjax.org).
+The source of the docs is hosted in the
+[mathjax/mathjax-docs](http://github.com/mathjax/mathjax-docs) repo here on GitHub.
 
-The documentation is generated using
-[Sphinx-doc](http://sphinx-doc.org/) and hosted on [Read the
-docs](http://readthedocs.org). The source of the docs is hosted in the
-[MathJax-Docs GitHub
-repository](http://github.com/mathjax/mathjax-docs).
-
+The documentation is generated using [Sphinx-doc](http://sphinx-doc.org/) and hosted on 
+[Read the docs](http://readthedocs.org).
 You can clone the repo and submit pull requests following the
-[pull-request](#pull-requests) guidelines.
+[pull-request](#submitting-pull-requests) guidelines.
 
 
 ### Translation
 
 If you wish to add or update translations of MathJax, please do it on
 [TranslateWiki.net](https://translatewiki.net/w/i.php?title=Special:Translate&group=out-mathjax-0-all)
 (and while you're there you can help other open source projects,
-too!).
+too, because you're awesome!).
 
 For bug reports and other questions that don't fit on
 TranslateWiki.net, head over to the
 [mathjax/mathjax-i18n](https://github.com/mathjax/MathJax-i18n)
 repository.
 
-
-## Working on MathJax Core {core}
-
-### Key Branches & Tags
-
-- **[develop](https://github.com/MathJax/MathJax/tree/develop)** is
-  the development branch. All work on the next release is here. Do
-  **NOT** use this branch for a production site.
-- **[master](https://github.com/MathJax/MathJax)** contains the latest
-  release of MathJax. This branch may be used in production.
-
-
-# Conduct
+## Conduct
 
 We are committed to providing a friendly, safe and welcoming environment for
 all, regardless of gender, sexual orientation, disability, ethnicity, religion,
@@ -252,9 +250,9 @@ behaviour is not welcome.
 We also suggest to read [discourse's
 rules](http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/)
 
-### References
+## References
 
-* We heavily borrowed from -- thanks to Mozilla and Ghost!
+* We heavily borrowed from Mozilla and Ghost -- thank you!
   * https://github.com/TryGhost/Ghost/blob/master/CONTRIBUTING.md
   * https://github.com/mozilla/rust/wiki/Note-development-policy
 * https://github.com/jden/CONTRIBUTING.md/blob/master/CONTRIBUTING.md