| commit | author | age | ||
| 83c3f6 | 1 | # Contributing to MathJax |
| SP | 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** — check if the issue has already been | |
| 48 | reported. | |
| 49 | ||
| 50 | 2. **Check if the issue has been fixed** — 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** — without a live page it is usually impossible to debug problems; see also the Bug Report Template below. | |
| 55 | ||
| 56 | 4. **Isolate the problem** — 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** — 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/ | |
