| 1 | ## csg.js
|
| 2 |
|
| 3 | ## Constructive Solid Geometry Library - Contributing Guide
|
| 4 |
|
| 5 | This library is part of the JSCAD Organization, and is maintained by a group of volunteers. We welcome and encourage anyone to pitch in but please take a moment to read the following guidelines.
|
| 6 |
|
| 7 | * If you want to submit a bug report please make sure to follow the [Reporting Issues](https://github.com/jscad/csg.js/wiki/Reporting-Issues) guide. Bug reports are accepted as [Issues](https://github.com/jscad/csg.js/issues/) via GitHub.
|
| 8 |
|
| 9 | * If you want to submit a change or a patch, please read the contents below on how to make changes. New contributions are accepted as [Pull Requests](https://github.com/jscad/csg.js/pulls/) via GithHub.
|
| 10 |
|
| 11 | * We only accept bug reports and pull requests on **GitHub**.
|
| 12 |
|
| 13 | * If you have a question about how to use CSG.js, then please start a conversation at the [OpenJSCAD.org User Group](https://plus.google.com/communities/114958480887231067224). You might find the answer in the [OpenJSCAD.org User Guide](https://github.com/Spiritdude/OpenJSCAD.org/wiki/User-Guide).
|
| 14 |
|
| 15 | * If you have a change or new feature in mind, please start a conversation with the [Core Developers](https://plus.google.com/communities/114958480887231067224) and start contributing changes.
|
| 16 |
|
| 17 | Thanks!
|
| 18 |
|
| 19 | The JSCAD Organization
|
| 20 |
|
| 21 | ## Making Changes
|
| 22 |
|
| 23 | First, we suggest that you fork this GIT repository. This will keep your changes separate from the fast lane. And make pull requests easier.
|
| 24 |
|
| 25 | Once forked, clone your copy of the CSG library.
|
| 26 | ```
|
| 27 | git clone https://github.com/myusername/csg.js.git
|
| 28 | cd csg.js
|
| 29 | ```
|
| 30 |
|
| 31 | **We suggest downloading NPM. This will allow you to generate API documents, and run test suites.**
|
| 32 |
|
| 33 | Once you have NPM, install all the dependencies for development.
|
| 34 | ```
|
| 35 | npm install
|
| 36 | ```
|
| 37 | And, run the test cases to verify the library is functional.
|
| 38 | ```
|
| 39 | npm test
|
| 40 | ```
|
| 41 | And, create the API documentation.
|
| 42 | ```
|
| 43 | npm run build-docs
|
| 44 | ```
|
| 45 |
|
| 46 | The project is structured as:
|
| 47 | - csg.js : library source code
|
| 48 | - test/*.js : various test suites
|
| 49 | - helpers/*.js : various helper classes for testing
|
| 50 | - objects/* : objects created by test suites
|
| 51 | - doc/* : generated API documentation
|
| 52 |
|
| 53 | You can now make changes to the library, as well as the test suites.
|
| 54 |
|
| 55 | If you intend to contribute changes back to JSCAD then please be sure to create test cases.
|
| 56 |
|
| 57 | Done? Great! Push the changes back to the fork.
|
| 58 | ```
|
| 59 | git commit changed-file
|
| 60 | git add test/new-test-suite.js
|
| 61 | git commit test/new-test-suite.js
|
| 62 | git push
|
| 63 | ```
|
| 64 | Finally, you can review your changes via GitHub, and create a pull request.
|
| 65 |
|
| 66 | TIPS for successful pull requests:
|
| 67 | - Commit often, and comment well
|
| 68 | - Follow the [JavaScript Standard Style](https://github.com/feross/standard)
|
| 69 | - Create test cases for all changes
|
| 70 | - Verify that all tests suites pass
|
| 71 |
|
| 72 | WOW! Thanks for the cool code.
|
| 73 |
|