|
1 | | -#MathLive Programming Guide |
| 1 | +# Contributing to MathLive |
2 | 2 |
|
3 | | -MathLive can be used to beautifully render and edit math in web pages. |
| 3 | +There are many ways you can get involved with MathLive. Contributing to |
| 4 | +an open source project is fun and rewarding. |
4 | 5 |
|
5 | | -This guide describes how to use the MathLive Javascript libraries in your own |
6 | | -web content. To contribute to the MathLive project, see the MathLive |
7 | | -Contributor Guide. |
| 6 | +## Contributings Issues |
8 | 7 |
|
9 | | -## Overview |
| 8 | +If you're running into some problems using MathLive or something doesn't |
| 9 | +behave the way you think it should, please file an issue in GitHub. |
10 | 10 |
|
11 | | -``` |
12 | | -``` |
| 11 | +Before filing something, [have a look](https://github.com/arnog/mathlive/issues) |
| 12 | +at the existing issues. It's better to avoid filing duplicates. You can |
| 13 | +add a comment to an existing issue if you'd like. |
13 | 14 |
|
14 | | -## Getting Started |
| 15 | +### What happens after I file an issue? |
15 | 16 |
|
16 | | -The MathLive library is a series of Javascript modules and a few |
17 | | -CSS files. The modules can be combined into a single library |
18 | | -using a bundler such as **webpack**, or they can be included |
19 | | -individually. We recommend to use **require.js** to simplify |
20 | | -and optimize the loading of the individual modules. |
| 17 | +1. After a bug is filed, it will be _awaiting review_ (the issue will be untagged) |
| 18 | +2. After the bug has been triaged, it will be tagged _reviewed_ |
| 19 | +3. Once a developer has started working on the bug, it will be tagged _fix in progress_. If the bug is a feature rather than a bug, it will be tagged _moved to backlog_ |
| 20 | +4. Once a bug has been fixed, it will be tagged _fixed_ |
21 | 21 |
|
22 | | -To use **require.js**, include the following in your web page, |
23 | | -preferably before the `</body>` tag: |
| 22 | +In addition, issues can be tagged with the following: |
| 23 | +* _high priority_: Catastrophic issue that impacts many users |
| 24 | +* _medium priority_: Regression or issues that impact a significant number of users |
| 25 | +* _low priority_: Low severity (minor cosmetic issue) or very few users impacted |
| 26 | +* _no priority_: No plan to fix the issue, but we will consider a fix if someone offers a pull request |
| 27 | +* _starter bug_: This is an issue that would be a good candidate for someone |
| 28 | +who has little experience with the code base |
| 29 | +* _external_: This is an issue that has a dependency on an external component |
| 30 | +(typically, a browser) |
| 31 | +* _architecture_: This is an issue that requires a significant architectural |
| 32 | +change |
| 33 | +* _performance_: This issue affects perceived or measurable performance |
| 34 | +* _cleanup_: Resolving this issue would improve the code base maintainability |
| 35 | +without adding new functionality |
| 36 | +* _utr_: _unable to reproduce_ the bug, as reported, could not be replicated |
| 37 | +by the developer. Additional information is necessary to continue investigating. |
| 38 | +* _nab_: _not a bug_: The behavior described in the issue report is actually |
| 39 | +the intended behavior. This may be a usability issue, a documentation issue, |
| 40 | +or a disagreement regarding what the behavior should be. |
| 41 | +* _fol_: _fact of life_: The issue cannot be resolved due to constraints of |
| 42 | +the browser, the OS, or the laws of physics. |
24 | 43 |
|
25 | | -``` |
26 | | -<script data-main="js/main" src="js/vendor/require.js"></script> |
27 | | -``` |
| 44 | +### Can I help fix a bug? |
28 | 45 |
|
29 | | -``js/main`` should be a path to your "main" file, without the `.js` |
30 | | -extension. |
| 46 | +Sure! Have a look at the issue report, and make sure no one is already |
| 47 | +working on it. If the issue is tagged _fix in progress_, someone is already |
| 48 | +on it. Otherwise, add a comment in the issue indicating you'd like to work on |
| 49 | +resolving the issue and go for it! See the [Contributor Guide](CONTRIBUTOR_GUIDE.md) for coding guidelines. |
31 | 50 |
|
32 | | -Inside `main.js`, use the following: |
33 | | -``` |
34 | | -define(['mathlive'], function(MathLive) { |
35 | 51 |
|
36 | | - // YOUR CODE GOES HERE |
| 52 | +## Contributings Test Cases |
37 | 53 |
|
38 | | -}); |
39 | | -``` |
| 54 | +The `test/` folder contains test cases that are used to make sure that |
| 55 | +bugs are not introduced as new features are added (regression). |
40 | 56 |
|
| 57 | +If you'd like to revise or add some new test cases, that can be very helpful |
| 58 | +to improve MathLive's quality. Submit an issue indicating what you'd like |
| 59 | +to work on, and a pull request when you have it ready. Test cases should |
| 60 | +follow the TAP (Test Anything Protocol) format. |
41 | 61 |
|
42 | | -## Rendering math automatically |
43 | 62 |
|
44 | | -Math in a web page can automatically be rendered after the page has |
45 | | -loaded using the `auto-render` module. |
| 63 | +## Contributing Ideas and Feature Requests |
46 | 64 |
|
47 | | -By default, any text that is enclosed with the following delimiters |
48 | | -will be converted to a math formula: |
49 | | -* `$$`...`$$` |
50 | | -* `\[`...`\]` |
51 | | -* `\(`...`\)` |
| 65 | +Use the [issue tracker](https://github.com/arnog/mathlive/issues) to submit |
| 66 | +requests for new features. First, have a look at what might already be there, |
| 67 | +and if you don't see anything that matches, write up a new issue. |
52 | 68 |
|
53 | | -When being considered for conversion, some tags are ignored: `script`, `noscript`, `style`, `textarea`, `pre` and `code`. |
| 69 | +## Contributing Code |
54 | 70 |
|
55 | | -To use this module, add it to the list of modules you import, for example: |
56 | | -``` |
57 | | -define(['mathlive', 'auto-render'], function(MathLive, AutoRender) { |
| 71 | +Whether you have a fix for an issue, some improved test cases, or a brand |
| 72 | +new feature, we welcome contributions in the form of pull requests. |
| 73 | +Once submitted, your pull request will be reviewed and you will receive |
| 74 | +some feedback to make sure that your pull request fits in with |
| 75 | +* the roadmap for MathLive |
| 76 | +* the architecture of the project |
| 77 | +* the coding guidelines of the project |
58 | 78 |
|
59 | | - // YOUR CODE GOES HERE |
| 79 | +Before we can consider merging your pull request, you must sign the |
| 80 | +Contributor License Agreement here: |
60 | 81 |
|
61 | | -}); |
62 | | -``` |
| 82 | +<a href="https://cla-assistant.io/arnog/mathlive"><img src="https://cla-assistant.io/readme/badge/arnog/mathlive" alt="CLA assistant" /></a> |
63 | 83 |
|
64 | | -Alternatively, if you don't have a `main.js` file, you can load it |
65 | | -directly from your main page: |
| 84 | +Once your pull request has been accepted, it will be merged |
| 85 | +into the master branch. |
66 | 86 |
|
67 | | -``` |
68 | | -<!doctype html> |
69 | | -<html lang="en-US"> |
70 | | -<head> |
71 | | - ... |
72 | | -</head> |
73 | | -<body onload = " |
74 | | - requirejs.config({baseUrl:'js/'}); |
75 | | - requirejs(['auto-render'], function(AutoRender) { |
76 | | - AutoRender.renderMathInElement( |
77 | | - document.getElementsByTagName('body')[0]) |
78 | | - }); |
79 | | -"> |
80 | | -<h1>Taxicab Number</h1> |
81 | | -<p>The second taxicab number is $$1729 = 10^3 + 9^3 = 12^3 + 1^3$$</p> |
82 | | -
|
83 | | -<script data-main="js/main" src="js/vendor/require.js"></script> |
84 | | -</body> |
85 | | -</html> |
86 | | -``` |
87 | | - |
88 | | -If you dynamically generate content, you can request the autorenderer to run again using `AutoRender.renderMathInElement(el)`. |
89 | | - |
90 | | -The `renderMathInElement()` functions takes a second parameter which can be used to customize the list of delimiters to consider, and the tags to ignore. |
91 | | - |
92 | | - |
93 | | - |
94 | | -## Rendering math programatically |
95 | | - |
96 | | -To make use of the MathLive API, include the MathLive module. |
97 | | - |
98 | | - |
99 | | -## Math Editor |
100 | | - |
101 | | - |
102 | | - |
103 | | -#MathLive Contributor Guide |
104 | | - |
105 | | -This guide describes how to make contributions to the MathLive project. If you |
106 | | -simply want to use MathLive with your web content, see the MathLive Programming |
107 | | -Guide. |
108 | | - |
109 | | -## Code structure |
110 | | - |
111 | | - |
112 | | -## Architecture |
| 87 | +Congratulations, you've become a Mathlive contributor! Thanks for your help! |
0 commit comments