mathjax/asset/CONTRIBUTING.md

   1 # Contributing to MathJax
   2
   3 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.
   4
   5 There are lots and lots of ways to get involved, this document covers:
   6
   7 * [reporting an issue](#reporting-an-issue)
   8     * [bug reports](#bug-reports)
   9     * [feature requests](#feature-requests)
  10     * [change requests](#change-requests)
  11 * [working on MathJax core](#working-on-mathjax-core)
  12     * [key branches and tags](#key-branches--tags)
  13     * [submitting pull requests](#submitting-pull-requests)
  14     * [testing and quality assurance](#testing-and-quality-assurance)
  15     * [writing documentation](#writing-documentation)
  16     * [translation](#translation)
  17 * [Conduct](#conduct)
  18
  19
  20 ## Reporting An Issue
  21
  22 If you're about to raise an issue because you think you've found a
  23 problem with MathJax, or you'd like to make a request for a new
  24 feature in the codebase, or any other reason… please read this first.
  25
  26 The GitHub issue tracker is the preferred channel for [bug reports](#bug-reports),
  27 [feature requests](#feature-requests), [change requests](#change-requests) and [submitting pull
  28 requests](#submitting-pull-requests), but please respect the following restrictions:
  29
  30 * Please **search for existing issues**. Help us keep duplicate issues
  31   to a minimum by checking to see if someone has already reported your
  32   problem or requested your idea.
  33
  34 * Please **do not** use the issue tracker for personal support
  35   requests (use [the MathJax User Group](https://groups.google.com/forum/#!forum/mathjax-users)).
  36
  37 * Please **be civil**. Keep the discussion on topic and respect the
  38   opinions of others. See also our [Conduct Guidelines](#conduct)
  39
  40 ### Bug Reports
  41
  42 A bug is a _demonstrable problem_ that is caused by the code in the repository.
  43 Good bug reports are extremely helpful - thank you!
  44
  45 Guidelines for bug reports:
  46
  47 1. **Use the GitHub issue search** &mdash; check if the issue has already been
  48    reported.
  49
  50 2. **Check if the issue has been fixed** &mdash; look for [closed issues in the
  51    current milestone](https://github.com/MathJax/MathJax/issues?&page=1&state=closed) or try to reproduce it
  52    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.
  53
  54 3. **Share a live sample of the problem** &mdash; without a live page it is usually impossible to debug problems; see also the Bug Report Template below.
  55
  56 4. **Isolate the problem** &mdash; a live sample is a starting point but if you want to speed things up create a [reduced test
  57    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.
  58
  59 5. **Include a screenshot/cast as a last resort** &mdash; Is your issue about a layout
  60    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!
  61
  62 6. Use the Bug Report template below or [click this
  63    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)
  64    to start creating a bug report with the template automatically.
  65
  66 A good bug report shouldn't leave others needing to chase you up for
  67 more information. Be sure to include the details of your environment.
  68
  69 Here is a [real example](https://github.com/mathjax/MathJax/issues/820)
  70
  71 Template Example ([click to use](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)):
  72 ```
  73 Short and descriptive example bug report title
  74
  75 ### Issue Summary
  76
  77 A summary of the issue and the browser/OS environment in which it occurs. If
  78 suitable, include the steps required to reproduce the bug.
  79
  80 ### Steps to Reproduce
  81
  82 1. This is the first step
  83 2. This is the second step
  84 3. Further steps, etc.
  85
  86 Any other information you want to share that is relevant to the issue
  87 being reported. Especially, why do you consider this to be a bug? What
  88 do you expect to happen instead?
  89
  90 ### Technical details:
  91
  92 * MathJax Version: 2.3 (latest commit: f3aaf3a2a3e964df2770dc4aaaa9c87ce5f47e2c)
  93 * Client OS: Mac OS X 10.8.4
  94 * Browser: Chrome 29.0.1547.57
  95 ```
  96
  97
  98 ### Feature Requests
  99
 100 Feature requests are welcome. Before you submit one be sure to have:
 101
 102 1. Read the
 103    [Roadmaps](https://github.com/mathjax/MathJax/wiki/Mathjax-roadmap),
 104    **use the GitHub search** and check the feature hasn't already been
 105    requested.
 106 2. Take a moment to think about whether your idea fits with the scope
 107    and aims of the project, or if it might better fit being a [custom
 108    extension](https://github.com/mathjax/MathJax-third-party-extensions).
 109 3. Remember, it's up to *you* to make a strong case to convince the
 110    project's leaders of the merits of this feature. Please provide as
 111    much detail and context as possible, this means explaining the use
 112    case and why it is likely to be common.
 113 4. Clearly indicate whether this is a feature request for MathJax
 114    core, input & output jax, or extensions.
 115
 116
 117 ### Change Requests
 118
 119 Change requests cover both architectural and functional changes to how
 120 MathJax works. If you have an idea for a new or different dependency,
 121 a refactor, or an improvement to a feature, etc - please be sure to:
 122
 123 1. **Use the GitHub search** and check someone else didn't get there first
 124 2. Take a moment to think about the best way to make a case for, and
 125    explain what you're thinking. Are you sure this shouldn't really be
 126    a [bug report](#bug-reports) or a [feature
 127    request](#feature-requests)?  Is it really one idea or is it many?
 128    What's the context? What problem are you solving? Why is what you
 129    are suggesting better than what's already there? Does it fit with
 130    the Roadmap?
 131
 132 ## Working on MathJax core
 133
 134 You want to contribute code? Fantastic! Let's get you started.
 135
 136 ### Key Branches & Tags
 137
 138 To get it out of the way:
 139
 140 - **[develop](https://github.com/MathJax/MathJax/tree/develop)** is
 141   the development branch. All work on the next release happens here so
 142   you should generally branch off `develop`. Do **NOT** use this branch
 143   for a production site.
 144 - **[master](https://github.com/MathJax/MathJax)** contains the latest
 145   release of MathJax. This branch may be used in production. Do
 146   **NOT** use this branch to work on MathJax's source.
 147
 148 ### Submitting Pull Requests
 149
 150 Pull requests are awesome. If you're looking to raise a PR for
 151 something which doesn't have an open issue, please think carefully
 152 about [raising an issue](#reporting-an-issue) which your PR can close,
 153 especially if you're fixing a bug. This makes it more likely that
 154 there will be enough information available for your PR to be properly
 155 tested and merged.
 156
 157 ##### Need Help?
 158
 159 If you're not completely clear on how to submit / update / *do* Pull
 160 Requests, please check out our [source control
 161 policies](https://github.com/mathjax/MathJax/wiki/Source-control-policies). For
 162 more insights, chech the excellent in depth [Git Workflow
 163 guide](https://github.com/TryGhost/Ghost/wiki/Git-Workflow) from
 164 Ghost, in particular
 165
 166 * [Ghost Workflow guide: commit messages](https://github.com/TryGhost/Ghost/wiki/Git-workflow#commit-messages)
 167
 168 ### Testing and Quality Assurance
 169
 170 Never underestimate just how useful quality assurance is. If you're
 171 looking to get involved with the code base and don't know where to
 172 start, checking out and testing a pull request is one of the most
 173 useful things you could do.
 174
 175 If you want to get involved with testing MathJax, there is a set of QA
 176 Documentation [in our testing
 177 framework](https://github.com/MathJax/MathJax-test).
 178
 179 Essentially though, [check out the latest develop
 180 branch](#working-on-mathJax-core), take it for a spin, and if you find
 181 anything odd, please follow the [bug report guidelines](#bug-reports)
 182 and let us know!
 183
 184 #### Checking out a Pull Request
 185
 186 These are some [excellent
 187 instructions](https://gist.github.com/piscisaureus/3342247) on
 188 configuring your GitHub repository to allow you to checkout pull
 189 requests in the same way as branches:
 190 <https://gist.github.com/piscisaureus/3342247>.
 191
 192
 193 ### Writing documentation
 194
 195 MathJax's main documentation can be found at [docs.mathjax.org](http://docs.mathjax.org).
 196 The source of the docs is hosted in the
 197 [mathjax/mathjax-docs](http://github.com/mathjax/mathjax-docs) repo here on GitHub.
 198
 199 The documentation is generated using [Sphinx-doc](http://sphinx-doc.org/) and hosted on
 200 [Read the docs](http://readthedocs.org).
 201 You can clone the repo and submit pull requests following the
 202 [pull-request](#submitting-pull-requests) guidelines.
 203
 204
 205 ### Translation
 206
 207 If you wish to add or update translations of MathJax, please do it on
 208 [TranslateWiki.net](https://translatewiki.net/w/i.php?title=Special:Translate&group=out-mathjax-0-all)
 209 (and while you're there you can help other open source projects,
 210 too, because you're awesome!).
 211
 212 For bug reports and other questions that don't fit on
 213 TranslateWiki.net, head over to the
 214 [mathjax/mathjax-i18n](https://github.com/mathjax/MathJax-i18n)
 215 repository.
 216
 217 ## Conduct
 218
 219 We are committed to providing a friendly, safe and welcoming environment for
 220 all, regardless of gender, sexual orientation, disability, ethnicity, religion,
 221 or similar personal characteristic.
 222
 223 Please be kind and courteous. There's no need to be mean or rude.
 224 Respect that people have differences of opinion and that every design or
 225 implementation choice carries a trade-off and numerous costs. There is seldom
 226 a right answer, merely an optimal answer given a set of values and
 227 circumstances.
 228
 229 Please keep unstructured critique to a minimum. If you have solid ideas you
 230 want to experiment with, make a fork and see how it works.
 231
 232 We will exclude you from interaction if you insult, demean or harass anyone.
 233 That is not welcome behaviour. We interpret the term "harassment" as
 234 including the definition in the
 235 [Citizen Code of Conduct](http://citizencodeofconduct.org/);
 236 if you have any lack of clarity about what might be included in that concept,
 237 please read their definition. In particular, we don't tolerate behavior that
 238 excludes people in socially marginalized groups.
 239
 240 Private harassment is also unacceptable. No matter who you are, if you feel
 241 you have been or are being harassed or made uncomfortable by a community
 242 member, please contact one of the channel ops or any of the
 243 [MathJax](https://github.com/MathJax/MathJax) core team
 244 immediately. Whether you're a regular contributor or a newcomer, we care about
 245 making this community a safe place for you and we've got your back.
 246
 247 Likewise any spamming, trolling, flaming, baiting or other attention-stealing
 248 behaviour is not welcome.
 249
 250 We also suggest to read [discourse's
 251 rules](http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/)
 252
 253 ## References
 254
 255 * We heavily borrowed from Mozilla and Ghost -- thank you!
 256   * https://github.com/TryGhost/Ghost/blob/master/CONTRIBUTING.md
 257   * https://github.com/mozilla/rust/wiki/Note-development-policy
 258 * https://github.com/jden/CONTRIBUTING.md/blob/master/CONTRIBUTING.md
 259 * http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/