|
| 1 | +# Contributing <a id="contribute"></a> |
| 2 | + |
| 3 | +## Issues and Suggestions |
| 4 | + |
| 5 | +If you discover bugs or missing features, please post them as GitHub issues. Be extremely detailed and thorough in your explanation of the issue/suggestion and why it's important to address it. |
| 6 | + |
| 7 | +Note that it will not be a high priority for the Bscotch team to address issues and feature that we ourselves don't actively need. To make your own fixes/features, see the next section. |
| 8 | + |
| 9 | +## Contributing Code |
| 10 | + |
| 11 | +The fastest way to get fixes and features is to submit them yourself! By forking this repo and making changes, you can have your own version that works however you want. |
| 12 | + |
| 13 | +If you want to bring your changes back into the main repo, you can make a pull request to do so. Note that your code will be under strict requirements to make sure that things don't turn into spaghetti: |
| 14 | + |
| 15 | +- Code must be fully typed Typescript (no `as any` or `//ts-ignore` unless absolutely necessary). |
| 16 | +- If adding a similar feature to something that already exists, the code must follow a similar pattern and re-use as much existing code as possible (no DRY violations). |
| 17 | +- Names of variables, methods, etc. must be consistent with those already in the project. |
| 18 | +- There must be test cases that cover your changes/additions (see `src/test/`). |
| 19 | +- The pull request must be git-rebase-able on the HEAD of the `develop` branch without conflict. |
| 20 | +- Commit messages must follow the project conventions (below). |
| 21 | + |
| 22 | +## Setting up your development environment |
| 23 | + |
| 24 | +After forking this repo to your own GitHub account |
| 25 | +and cloning locally: |
| 26 | + |
| 27 | +- Open a terminal in the root of this project. |
| 28 | + - Run `npm install` |
| 29 | + - Run `npm run build` |
| 30 | + - Run `npm test` |
| 31 | +- If all tests are passing, you're good to go! |
| 32 | + |
| 33 | +## How to test your code |
| 34 | + |
| 35 | +If you are using Visual Studio Code, you can open |
| 36 | +up the debug panel from the sidebar and hit the play |
| 37 | +button to run tests. Output will appear in your Debug |
| 38 | +Console. |
| 39 | + |
| 40 | +To compile the code into JavaScript, run |
| 41 | +`npm run build`. Alternatively, you can run the Typescript |
| 42 | +compiler in watch mode to re-compile the code every time |
| 43 | +you save a change, using `npx tsc -w`. |
| 44 | + |
| 45 | +## Commit conventions |
| 46 | + |
| 47 | +All of your commits must follow the conventions below. |
| 48 | +We recommend squashing your commits into one commit per |
| 49 | +feature/bugfix, but that isn't required. |
| 50 | + |
| 51 | +We follow the conventional-changelog Angular convention for commit messages, |
| 52 | +namely formatting them as `<type>: <subject>` where `type` is one of: |
| 53 | + |
| 54 | +- feat: A new feature |
| 55 | +- fix: A bug fix |
| 56 | +- refactor: A code change that neither fixes a bug nor adds a feature |
| 57 | +- test: Adding missing or correcting existing tests |
| 58 | +- docs: Documentation only changes |
| 59 | +- perf: A code change that improves performance |
| 60 | +- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation |
0 commit comments