CONTRIBUTING.md (12176B)
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** — 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-testing). 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/