315 lines
14 KiB
Markdown
315 lines
14 KiB
Markdown
# Contributing to MathJax
|
|
|
|
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:
|
|
|
|
* [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)
|
|
* [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)
|
|
* [Conduct](#conduct)
|
|
|
|
|
|
## Reporting An Issue
|
|
|
|
If you're about to raise an issue because you think you've found a
|
|
problem with MathJax, or you'd like to make a request for a new
|
|
feature in the codebase, or any other reason, please read this first.
|
|
|
|
The [MathJax issue
|
|
tracker](https://github.com/mathjax/MathJax/issues) is the
|
|
preferred channel for [bug reports](#bug-reports), [feature
|
|
requests](#feature-requests), [change requests](#change-requests), and
|
|
[submitting pull requests](#submitting-pull-requests), but please
|
|
respect the following restrictions:
|
|
|
|
* Please **search for existing issues**. Help us keep duplicate issues
|
|
to a minimum by checking to see if someone has already reported your
|
|
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)).
|
|
|
|
* Please **be civil**. Keep the discussion on topic and respect the
|
|
opinions of others. See also our [Conduct Guidelines](#conduct)
|
|
|
|
### Bug Reports
|
|
|
|
A bug is a *demonstrable problem* that is caused by the code in the
|
|
repository. Good bug reports are extremely helpful — thank you!
|
|
|
|
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** — look for [closed
|
|
issues in the current
|
|
milestone](https://github.com/mathjax/MathJax/issues?q=is%3Aclosed)
|
|
or try to reproduce it using the latest `develop` branch. Please
|
|
note that you will need to
|
|
[compile MathJax and make the components](https://docs.mathjax.org/en/latest/web/hosting.html#getting-mathjax-via-git)
|
|
in order to test MathJax from the source repository.
|
|
|
|
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](#template) below.
|
|
|
|
4. **Isolate the problem** — a live sample is a starting point
|
|
but if you want to speed things up, create a [reduced test
|
|
case](https://css-tricks.com/reduced-test-cases/). Be specific
|
|
about your setup (browser, OS versions, etc). Use services like
|
|
[jsbin](http://jsbin.com), [CodePen](http://codepen.io), or
|
|
[jsFiddle](http://jsfiddle.com) to make collaboration on minimal
|
|
test cases easier for everyone.
|
|
|
|
5. **Include a screenshot/cast as a last resort** — Is your
|
|
issue about a layout or design feature or bug that is 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. If you make it an animated gif, you can
|
|
embed it directly into your GitHub issue.
|
|
|
|
6. Use the [Bug Report Template](#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.
|
|
|
|
A good bug report shouldn't leave others needing to request
|
|
more information from you. Be sure to include the details of your environment.
|
|
|
|
<a id="template"></a>
|
|
|
|
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)):
|
|
|
|
```
|
|
Short and descriptive example bug report title
|
|
|
|
### Issue Summary
|
|
|
|
A summary of the issue and the browser/OS environment in which it occurs. If
|
|
suitable, include the steps required to reproduce the bug.
|
|
|
|
### Steps to Reproduce
|
|
|
|
1. This is the first step
|
|
2. This is the second step
|
|
3. Further steps, etc.
|
|
|
|
Any other information you want to share that is relevant to the issue
|
|
being reported. Especially, why do you consider this to be a bug? What
|
|
do you expect to happen instead?
|
|
|
|
### Technical details:
|
|
|
|
* MathJax Version: 2.3 (latest commit: f3aaf3a2a3e964df2770dc4aaaa9c87ce5f47e2c)
|
|
* Client OS: Mac OS X 10.8.4
|
|
* Browser: Chrome 29.0.1547.57
|
|
```
|
|
|
|
|
|
### Feature Requests
|
|
|
|
Feature requests are welcome. Before you submit one, be sure to have:
|
|
|
|
1. **Used the GitHub search** to check that the feature hasn't already
|
|
been requested.
|
|
2. Take a moment to think about whether your idea fits with the scope
|
|
and aims of the project, or if it might better fit being a [custom
|
|
extension](https://github.com/mathjax/MathJax-third-party-extensions).
|
|
3. Remember, it's up to *you* to make a strong case to convince the
|
|
project's leaders of the merits of this feature. Please provide as
|
|
much detail and context as possible, this means explaining the use
|
|
case and why it is likely to be common.
|
|
|
|
### Change Requests
|
|
|
|
Change requests cover both architectural and functional changes to how
|
|
MathJax works. If you have an idea for a new or different dependency,
|
|
a refactor, or an improvement to a feature, etc., please be sure to:
|
|
|
|
1. **Use the GitHub search** to check that someone else didn't get there first.
|
|
2. Take a moment to think about the best way to make a case for, and
|
|
explain what you're thinking. Are you sure this shouldn't really be
|
|
a [bug report](#bug-reports) or a [feature
|
|
request](#feature-requests)? Is it really one idea or is it many?
|
|
What's the context? What problem are you solving? Why is what you
|
|
are suggesting better than what's already there?
|
|
|
|
## Working on MathJax core
|
|
|
|
You want to contribute code? We describe how below. First, note that
|
|
the MathJax source code is in the
|
|
<https://github.com/mathjax/MathJax-src> repository, not the
|
|
<https://github.com/mathjax/MathJax> repository, which contains the
|
|
packaged component files for distribution on CDNs and the [mathjax npm
|
|
package](https://www.npmjs.com/package/mathjax) (the source code is
|
|
included in the [mathjax-full npm
|
|
package](https://www.npmjs.com/package/mathjax-full)).
|
|
|
|
### Key Branches & Tags
|
|
|
|
MathJax uses several permanent branches in the [MathJax source repository](https://github.com/mathjax/MathJax-src):
|
|
|
|
- **[develop](https://github.com/mathjax/MathJax-src/tree/develop)**
|
|
is the development branch. All work on the next release happens here
|
|
so you should generally branch off `develop` if you are going to
|
|
submit a pull request. Do **NOT** use this branch for a production
|
|
site.
|
|
|
|
- **[master](https://github.com/mathjax/MathJax-src)** contains the latest
|
|
release of MathJax. This branch may be used in production. Do
|
|
**NOT** use this branch to work on MathJax's source.
|
|
|
|
These branches reflect version 3 of MathJax, which is substantially
|
|
different from the version 2 codebase. Version 2 will continue to be
|
|
maintained while web sites transition to version 3, with work being
|
|
done using the following branches in the [MathJax distribution
|
|
repository](https://github.com/mathjax/MathJax):
|
|
|
|
- **[legacy-v2-develop](https://github.com/mathjax/MathJax/tree/legacy-v2-develop)**
|
|
is the development branch for changes to the legacy version 2 code.
|
|
Any pull requests for version 2 should be branched from here. Do
|
|
**NOT** use this branch for a production site.
|
|
|
|
- **[legacy-v2](https://github.com/mathjax/MathJax/tree/legacy-v2)**
|
|
is the branch that contains any updates to version 2 following
|
|
the release of version 3. Do **NOT** use this branch to work on
|
|
MathJax's source.
|
|
|
|
In addition to these branches, MathJax uses tags to identify the
|
|
various versions. These can be checked out to obtain the specified
|
|
release; for example, `git checkout 2.7.5` would get you the files for
|
|
version 2.7.5 of MathJax.
|
|
|
|
Note that version 3 is written in Typescript, and so must be compiled
|
|
to obtain usable javascript files, and that the components need to be
|
|
built once that is done. See the
|
|
[documentation](https://docs.mathjax.org/en/latest/web/hosting.html#getting-mathjax-via-git)
|
|
for details. For version 2, the source javascript files are not
|
|
compressed until a release is made, so you should use the copies in
|
|
the `unpacked` directory during development.
|
|
|
|
|
|
### Submitting Pull Requests
|
|
|
|
Pull requests are welcome. If you're looking to submit a PR for
|
|
something that doesn't have an open issue, please consider [raising an
|
|
issue](#reporting-an-issue) that 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.
|
|
|
|
##### Need Help?
|
|
|
|
If you're not completely clear on how to submit/update/*do* Pull
|
|
Requests, please check out our [source control
|
|
policies](https://github.com/mathjax/MathJax/wiki/Source-control-policies). For
|
|
more insights, check the excellent in depth [Git Workflow
|
|
guide](https://github.com/TryGhost/Ghost/wiki/Git-Workflow) from
|
|
Ghost, in particular
|
|
|
|
* [Ghost Workflow guide: commit messages](https://github.com/TryGhost/Ghost/wiki/Git-workflow#commit-messages)
|
|
|
|
### Testing and Quality Assurance
|
|
|
|
If you're
|
|
looking to get involved with the code base and don't know where to
|
|
start, checking out and testing a pull request is one of the most
|
|
useful things you could do.
|
|
|
|
These are some [excellent
|
|
instructions](https://gist.github.com/piscisaureus/3342247) on
|
|
configuring your GitHub repository to allow you to checkout pull
|
|
requests in the same way as branches.
|
|
|
|
|
|
### 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). You can clone the repo and submit pull
|
|
requests following the [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).
|
|
|
|
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.
|
|
|
|
The translation files currently are for version 2, as localization
|
|
hasn't been added to version 3 yet.
|
|
|
|
## Conduct
|
|
|
|
As a NumFOCUS fiscally sponsored project, MathJax is governed by the
|
|
[NumFOCUS code of conduct](https://numfocus.org/code-of-conduct),
|
|
which we summarize as follows:
|
|
|
|
We are committed to providing a friendly, safe and welcoming
|
|
environment for all, regardless of gender, sexual orientation,
|
|
disability, ethnicity, religion, or similar personal characteristic.
|
|
|
|
Please be kind and courteous. There's no need to be mean or rude.
|
|
Respect that people have differences of opinion and that every design
|
|
or implementation choice carries a trade-off and numerous costs. There
|
|
is seldom a right answer, merely an optimal answer given a set of
|
|
values and circumstances.
|
|
|
|
Please keep unstructured critique to a minimum. If you have solid
|
|
ideas you want to experiment with, make a fork and see how it works.
|
|
|
|
We will exclude you from interaction if you insult, demean or harass
|
|
anyone. That is not welcome behaviour. We interpret the term
|
|
"harassment" as including the definition in the [Unacceptable
|
|
Behavior](https://numfocus.org/code-of-conduct#unacceptable-behavior)
|
|
section of the [NumFOCUS code of
|
|
conduct](https://numfocus.org/code-of-conduct); if you have any lack
|
|
of clarity about what might be included in that concept, please read
|
|
that definition. In particular, we don't tolerate behavior that
|
|
excludes people in socially marginalized groups.
|
|
|
|
Private harassment is also unacceptable. No matter who you are, if you
|
|
feel you have been or are being harassed or made uncomfortable by a
|
|
community member, please contact one of the channel ops or any of the
|
|
[MathJax](https://github.com/MathJax/MathJax) core team
|
|
immediately. Whether you're a regular contributor or a newcomer, we
|
|
care about making this community a safe place for you and we've got
|
|
your back.
|
|
|
|
Likewise any spamming, trolling, flaming, baiting, or other
|
|
attention-stealing behaviour is not welcome.
|
|
|
|
We also recommend that you read [discourse's
|
|
rules](http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/)
|
|
for further suggestions on appropriate behavior.
|
|
|
|
## References
|
|
|
|
* 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>
|
|
* <http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/>
|