1 # Contributing to MathJax
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.
5 There are lots and lots of ways to get involved, this document covers:
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)
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.
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:
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.
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)).
37 * Please **be civil**. Keep the discussion on topic and respect the
38 opinions of others. See also our [Conduct Guidelines](#conduct)
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!
45 Guidelines for bug reports:
47 1. **Use the GitHub issue search** — check if the issue has already been
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.
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.
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.
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!
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.
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.
69 Here is a [real example](https://github.com/mathjax/MathJax/issues/820)
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)):
73 Short and descriptive example bug report title
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.
80 ### Steps to Reproduce
82 1. This is the first step
83 2. This is the second step
84 3. Further steps, etc.
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?
90 ### Technical details:
92 * MathJax Version: 2.3 (latest commit: f3aaf3a2a3e964df2770dc4aaaa9c87ce5f47e2c)
93 * Client OS: Mac OS X 10.8.4
94 * Browser: Chrome 29.0.1547.57
100 Feature requests are welcome. Before you submit one be sure to have:
103 [Roadmaps](https://github.com/mathjax/MathJax/wiki/Mathjax-roadmap),
104 **use the GitHub search** and check the feature hasn't already been
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.
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:
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
132 ## Working on MathJax core
134 You want to contribute code? Fantastic! Let's get you started.
136 ### Key Branches & Tags
138 To get it out of the way:
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.
148 ### Submitting Pull Requests
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
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
166 * [Ghost Workflow guide: commit messages](https://github.com/TryGhost/Ghost/wiki/Git-workflow#commit-messages)
168 ### Testing and Quality Assurance
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.
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).
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)
184 #### Checking out a Pull Request
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>.
193 ### Writing documentation
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.
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.
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!).
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)
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.
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
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.
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.
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.
247 Likewise any spamming, trolling, flaming, baiting or other attention-stealing
248 behaviour is not welcome.
250 We also suggest to read [discourse's
251 rules](http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/)
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/