From 79127fb44bf51790f76731a8094147976f43f6a1 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Thu, 16 Apr 2015 10:51:17 +0200 Subject: [PATCH 1/3] Updating Commit.md * fix broken links * re-write bug report instructions * restructure core development advice. --- CONTRIBUTING.md | 65 +++++++++++++++++++++++-------------------------- 1 file changed, 31 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a431da2b..d9f9b0b38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 From f22a1adab7e19bee881a2ec1d7337d51c311ed5c Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Thu, 16 Apr 2015 14:31:35 +0200 Subject: [PATCH 2/3] updating contributing.md * Fix more relative links * fix TOC structure * minor changes to core section --- CONTRIBUTING.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9f9b0b38..fd85a7d5c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,11 +8,12 @@ There are lots and lots of ways to get involved, this document covers: * [bug reports](#bug-reports) * [feature requests](#feature-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) -* [testing and quality assurance](#testing-and-quality-assurance) -* [writing documentation](#writing-documentation) -* [translation](#translation) + * [testing and quality assurance](#testing-and-quality-assurance) + * [writing documentation](#writing-documentation) + * [translation](#translation) * [Conduct](#conduct) @@ -137,10 +138,12 @@ You want to contribute code? Fantastic! Let's get you started. 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. + the development branch. All work on the next release happens here so + you should generally branch of `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. + release of MathJax. This branch may be used in production. Do + **NOT** use this branch to work on MathJax's source. ### Submitting Pull Requests @@ -187,16 +190,14 @@ requests in the same way as branches: . -### Documentation +### 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). The source of the docs is hosted in the -[MathJax-Docs GitHub -repository](http://github.com/mathjax/mathjax-docs). - +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. @@ -213,7 +214,7 @@ TranslateWiki.net, head over to the [mathjax/mathjax-i18n](https://github.com/mathjax/MathJax-i18n) repository. -# Conduct +## Conduct We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, @@ -249,7 +250,7 @@ behaviour is not welcome. We also suggest to read [discourse's rules](http://blog.discourse.org/2013/03/the-universal-rules-of-civilized-discourse/) -### References +## References * We heavily borrowed from Mozilla and Ghost -- thank you! * https://github.com/TryGhost/Ghost/blob/master/CONTRIBUTING.md From 3ad8dc5a29e0e7665b38feb7f0ba50680f3e5314 Mon Sep 17 00:00:00 2001 From: Peter Krautzberger Date: Thu, 16 Apr 2015 21:08:55 +0200 Subject: [PATCH 3/3] updated contributing.md Fixing typos to address comments --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fd85a7d5c..96ad9b625 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -139,7 +139,7 @@ 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 of `develop`. Do **NOT** use this branch + 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