suzanne.soy/scribble-mathjax
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #1168 from mathjax/issue1162

Browse Source 
Updating contributing.md
This commit is contained in:
Davide P. Cervone 2015-04-18 12:02:33 -04:00
commit e35dd5fd43
1 changed files with 45 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
CONTRIBUTING.md
View File

@ -1,20 +1,19 @@
# Contributing to MathJax # Contributing to MathJax
So you're interested in giving us a hand? That's awesome! We've put 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.
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: There are lots and lots of ways to get involved, this document covers:
* [raising issues](#raising-issues) * [reporting an issue](#reporting-an-issue)
* [bug reports](#bug-reports) * [bug reports](#bug-reports)
* [feature requests](#feature-requests) * [feature requests](#feature-requests)
* [change requests](#change-requests) * [change requests](#change-requests)
* [working on MathJax core](#working-on-MathJax-core) * [working on MathJax core](#working-on-mathjax-core)
* [key branches and tags](#key-branches--tags)
* [submitting pull requests](#submitting-pull-requests) * [submitting pull requests](#submitting-pull-requests)
* [testing and quality assurance](#testing-and-quality-assurance) * [testing and quality assurance](#testing-and-quality-assurance)
* [writing documentation](#writing-documentation) * [writing documentation](#writing-documentation)
* [translation](#translation) * [translation](#translation)
* [Conduct](#conduct) * [Conduct](#conduct)
@ -33,7 +32,7 @@ requests](#submitting-pull-requests), but please respect the following restricti
problem or requested your idea. problem or requested your idea.
* Please **do not** use the issue tracker for personal support * Please **do not** use the issue tracker for personal support
requests (use [the MathJax User Group](https://groups.google.com/forum/#!forum/mathjax-users). 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 * Please **be civil**. Keep the discussion on topic and respect the
opinions of others. See also our [Conduct Guidelines](#conduct) opinions of others. See also our [Conduct Guidelines](#conduct)
@ -48,21 +47,19 @@ Guidelines for bug reports:
1. **Use the GitHub issue search** — check if the issue has already been 1. **Use the GitHub issue search** — check if the issue has already been
reported. reported.
2. **Check if the issue has been fixed** — try to reproduce it 2. **Check if the issue has been fixed** — look for [closed issues in the
using the latest `develop` or look for [closed issues in the current milestone](https://github.com/MathJax/MathJax/issues?&page=1&state=closed) or try to reproduce it
current milestone](https://github.com/MathJax/MathJax/issues?&page=1&state=closed). 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.
3. **Isolate the problem** — ideally create a [reduced test 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.
case](http://css-tricks.com/6263-reduced-test-cases/) and a live example.
4. **Include a screencast if relevant** - Is your issue about a design 4. **Isolate the problem** — a live sample is a starting point but if you want to speed things up create a [reduced test
or front end feature or bug? The most helpful thing in the world is 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.
if we can *see* what you're talking about. Use
[LICEcap](http://www.cockos.com/licecap/) to quickly and easily
record a short screencast (24fps) and save it as an animated gif!
Embed it directly into your GitHub issue. Kapow.
5. Use the Bug Report template below or [click this 5. **Include a screenshot/cast as a last resort** — Is your issue about a layout
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!
6. Use the Bug Report 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) 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. to start creating a bug report with the template automatically.
@ -132,12 +129,27 @@ a refactor, or an improvement to a feature, etc - please be sure to:
are suggesting better than what's already there? Does it fit with are suggesting better than what's already there? Does it fit with
the Roadmap? the Roadmap?
## Working on MathJax core
You want to contribute code? Fantastic! Let's get you started.
### Key Branches & Tags
To get it out of the way:
- **[develop](https://github.com/MathJax/MathJax/tree/develop)** is
the development branch. All work on the next release happens here so
you should generally branch off `develop`. Do **NOT** use this branch
for a production site.
- **[master](https://github.com/MathJax/MathJax)** contains the latest
release of MathJax. This branch may be used in production. Do
**NOT** use this branch to work on MathJax's source.
### Submitting Pull Requests ### Submitting Pull Requests
Pull requests are awesome. If you're looking to raise a PR for Pull requests are awesome. If you're looking to raise a PR for
something which doesn't have an open issue, please think carefully something which doesn't have an open issue, please think carefully
about [raising an issue](#raising-issues) which your PR can close, about [raising an issue](#reporting-an-issue) which your PR can close,
especially if you're fixing a bug. This makes it more likely that 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 there will be enough information available for your PR to be properly
tested and merged. tested and merged.
@ -165,7 +177,7 @@ Documentation [in our testing
framework](https://github.com/MathJax/MathJax-testing). framework](https://github.com/MathJax/MathJax-testing).
Essentially though, [check out the latest develop Essentially though, [check out the latest develop
branch](#contribute-to-core), take it for a spin, and if you find branch](#working-on-mathJax-core), take it for a spin, and if you find
anything odd, please follow the [bug report guidelines](#bug-reports) anything odd, please follow the [bug report guidelines](#bug-reports)
and let us know! and let us know!
@ -178,18 +190,16 @@ requests in the same way as branches:
<https://gist.github.com/piscisaureus/3342247>. <https://gist.github.com/piscisaureus/3342247>.
### Documentation ### Writing documentation
MathJax's main documentation can be found at [docs.mathjax.org](http://docs.mathjax.org). 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 The documentation is generated using [Sphinx-doc](http://sphinx-doc.org/) and hosted on
[Sphinx-doc](http://sphinx-doc.org/) and hosted on [Read the [Read the docs](http://readthedocs.org).
docs](http://readthedocs.org). The source of the docs is hosted in the
[MathJax-Docs GitHub
repository](http://github.com/mathjax/mathjax-docs).
You can clone the repo and submit pull requests following the You can clone the repo and submit pull requests following the
[pull-request](#pull-requests) guidelines. [pull-request](#submitting-pull-requests) guidelines.
### Translation ### Translation
@ -197,26 +207,14 @@ You can clone the repo and submit pull requests following the
If you wish to add or update translations of MathJax, please do it on 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) [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, (and while you're there you can help other open source projects,
too!). too, because you're awesome!).
For bug reports and other questions that don't fit on For bug reports and other questions that don't fit on
TranslateWiki.net, head over to the TranslateWiki.net, head over to the
[mathjax/mathjax-i18n](https://github.com/mathjax/MathJax-i18n) [mathjax/mathjax-i18n](https://github.com/mathjax/MathJax-i18n)
repository. repository.
## Conduct
## Working on MathJax Core {core}
### Key Branches & Tags
- **[develop](https://github.com/MathJax/MathJax/tree/develop)** is
the development branch. All work on the next release is here. Do
**NOT** use this branch for a production site.
- **[master](https://github.com/MathJax/MathJax)** contains the latest
release of MathJax. This branch may be used in production.
# Conduct
We are committed to providing a friendly, safe and welcoming environment for We are committed to providing a friendly, safe and welcoming environment for
all, regardless of gender, sexual orientation, disability, ethnicity, religion, all, regardless of gender, sexual orientation, disability, ethnicity, religion,
@ -252,9 +250,9 @@ behaviour is not welcome.
We also suggest to read [discourse's We also suggest to read [discourse's
rules](http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/) rules](http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/)
### References ## References
* We heavily borrowed from -- thanks to Mozilla and Ghost! * We heavily borrowed from Mozilla and Ghost -- thank you!
* https://github.com/TryGhost/Ghost/blob/master/CONTRIBUTING.md * https://github.com/TryGhost/Ghost/blob/master/CONTRIBUTING.md
* https://github.com/mozilla/rust/wiki/Note-development-policy * https://github.com/mozilla/rust/wiki/Note-development-policy
* https://github.com/jden/CONTRIBUTING.md/blob/master/CONTRIBUTING.md * https://github.com/jden/CONTRIBUTING.md/blob/master/CONTRIBUTING.md