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

Updating Commit.md

Browse Source 
* fix broken links
* re-write bug report instructions
* restructure core development advice.
This commit is contained in:
Peter Krautzberger 2015-04-16 10:51:17 +02:00
parent 65937e6c4d
commit 79127fb44b
1 changed files with 31 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
CONTRIBUTING.md
View File

@ -1,12 +1,10 @@
# Contributing to MathJax
So you're 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.
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:
* [raising issues](#raising-issues)
* [reporting an issue](#reporting-an-issue)
* [bug reports](#bug-reports)
* [feature requests](#feature-requests)
* [change requests](#change-requests)
@ -33,7 +31,7 @@ requests](#submitting-pull-requests), but please respect the following restricti
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).
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)
@ -48,21 +46,19 @@ 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** — try to reproduce it
using the latest `develop` or look for [closed issues in the
current milestone](https://github.com/MathJax/MathJax/issues?&page=1&state=closed).
2. **Check if the issue has been fixed** — look for [closed issues in the
current milestone](https://github.com/MathJax/MathJax/issues?&page=1&state=closed) or try to reproduce it
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
case](http://css-tricks.com/6263-reduced-test-cases/) and a live example.
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.
4. **Include a screencast if relevant** - Is your issue about a design
or front end feature or bug? The most helpful thing in the world is
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.
4. **Isolate the problem** — a live sample is a starting point but if you want to speed things up create a [reduced test
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.
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)
to start creating a bug report with the template automatically.
@ -132,12 +128,25 @@ 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
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 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.
### Submitting Pull Requests
Pull requests are awesome. If you're looking to raise a PR for
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
there will be enough information available for your PR to be properly
tested and merged.
@ -165,7 +174,7 @@ Documentation [in our testing
framework](https://github.com/MathJax/MathJax-testing).
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)
and let us know!
@ -189,7 +198,7 @@ docs](http://readthedocs.org). The source of the docs is hosted in the
repository](http://github.com/mathjax/mathjax-docs).
You can clone the repo and submit pull requests following the
[pull-request](#pull-requests) guidelines.
[pull-request](#submitting-pull-requests) guidelines.
### Translation
@ -197,25 +206,13 @@ 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
[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!).
too, because you're awesome!).
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.
## 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
@ -254,7 +251,7 @@ rules](http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discou
### 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/mozilla/rust/wiki/Note-development-policy
* https://github.com/jden/CONTRIBUTING.md/blob/master/CONTRIBUTING.md