CONTRIBUTING.md (5594B)
1 # Contributing to KaTeX 2 3 We welcome pull requests to KaTeX. If you'd like to add a new symbol, or try to 4 tackle adding a larger feature, keep reading. If you have any questions, or want 5 help solving a problem, feel free to stop by our [gitter channel](https://gitter.im/Khan/KaTeX). 6 7 ## Helpful contributions 8 9 If you'd like to contribute, try contributing new symbols or functions that 10 KaTeX doesn't currently support. The wiki has a page which lists [all of the 11 supported 12 functions](https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX) as 13 well as a page that describes how to [examine TeX commands and where to find 14 rules](https://github.com/Khan/KaTeX/wiki/Examining-TeX) which can be quite 15 useful when adding new commands. There's also a user-contributed [preview page] 16 (http://utensil-site.github.io/available-in-katex/) 17 showing how KaTeX would render a series of symbols/functions (including the ones 18 MathJax listed in their documentation and the extra ones supported by KaTeX). You 19 can check them to see if we don't support a function you like, or try your 20 function in the interactive demo at 21 [http://khan.github.io/KaTeX/](http://khan.github.io/KaTeX/). 22 23 #### Single symbols 24 25 There are many individual symbols that KaTeX doesn't yet support. Read through 26 the [symbols.js](src/symbols.js) file for more information on how to add a 27 symbol. 28 29 To figure out the unicode symbol for the symbol you are trying to add, try using 30 the symbol in MathJax to see what unicode symbol it outputs. An interactive 31 MathJax shell can be found [here](http://fiddle.jshell.net/YpqVp/41/show/). 32 33 To figure out what group your symbol falls into, look through the symbols list 34 to find other symbols of a similar kind. (e.g. if you were adding `\neq`, look 35 for `=`). If you cannot find anything similar, or are unsure, you can try using 36 your symbol in TeX surrounded by other different kinds of symbols, and seeing 37 whether your spacing matches the spacing that TeX produces. 38 39 Once your symbol works, check the JavaScript console to make sure you don't get 40 a message like "Can't find character metrics for _" when you render your symbol. 41 If you do, check out [extract_ttfs.py](metrics/extract_ttfs.py). 42 43 #### Adding new functions 44 45 Most functions are handled in the [functions.js](src/functions.js) file. Read 46 the comments in there to get started. If the function you want to add has 47 similar output to an existing function, see if you can add a new line to that 48 file to get it to work. 49 50 If your function isn't similar to an existing function, you'll need to add a 51 line to `functions.js` as well as adding an output function in 52 [buildHTML.js](src/buildHTML.js) and [buildMathML.js](src/buildMathML.js). 53 54 ## Testing 55 56 Local testing can be done by running the node server in `server.js`. Run `make 57 setup` to install dependencies, and then `make serve` to start the server. 58 59 This will host an interactive editor at 60 [http://localhost:7936/](http://localhost:7936/) to play around with and test 61 changes. 62 63 #### Jasmine tests 64 65 The JavaScript parser and some of the tree 66 builder is tested with Jasmine. These tests can be run either using node with 67 `make test`, or in the browser by visiting 68 [http://localhost:7936/test/test.html](http://localhost:7936/test/test.html). 69 70 The Jasmine tests should be run after every change, even the addition of small 71 symbols. However, [Travis](https://travis-ci.org/Khan/KaTeX/) will run these 72 tests when you submit a pull request, in case you forget. 73 74 If you make any changes to Parser.js, add Jasmine tests to ensure they work. 75 76 #### Screenshot tests 77 78 To ensure the final output looks good, we screenshot different expressions. 79 These tests can be run by using the 80 [Screenshotter docker](https://github.com/Khan/KaTeX/tree/master/dockers/Screenshotter). 81 82 The screenshot tests should be run if you add anything more significant than 83 individual symbols. These tests are not automatically run, so please remember! 84 If the new images are different (meaning they are not byte-by-byte the same as 85 the old ones), inspect them visually. If there are no visible changes, that is 86 okay. If things change in a way consistent with your additions, explain what 87 changed and why. Otherwise, figure out what is causing the changes and fix it! 88 89 If you add a feature that is dependent on the final output looking the way you 90 created it, add a screenshot test. See 91 [ss_data.yaml](test/screenshotter/ss_data.yaml). 92 93 #### Testing in other browsers 94 95 KaTeX supports all major browsers, including IE 8 and newer. Unfortunately, it 96 is hard to test new changes in many browsers. If you can, please test your 97 changes in as many browsers as possible. In particular, if you make CSS changes, 98 try to test in IE 8, using [modern.ie](http://modern.ie) VMs. 99 100 ## Style guide 101 102 Code 103 104 - 4 spaces for indentation 105 - 80 character line length 106 - commas last 107 - declare variables in the outermost scope that they are used 108 - camelCase for variables in JavaScript 109 - snake_case for variables in Python 110 111 In general, try to make your code blend in with the surrounding code. 112 113 ## Pull Requests 114 115 - link back to the original issue(s) whenever possible 116 - new commands should be added to the [wiki](https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX) 117 - commits should be squashed before merging 118 - large pull requests should be broken into separate pull requests (or multiple logically cohesive commits), if possible 119 120 ## CLA 121 122 In order to contribute to KaTeX, you must first sign the CLA, found at www.khanacademy.org/r/cla 123 124 ## License 125 126 KaTeX is licenced under the [MIT License](http://opensource.org/licenses/MIT).