|
| 1 | +# Thanks for contributing to Scala CLI! |
| 2 | + |
| 3 | +This doc is meant as a guide on how best to contribute to Scala CLI. |
| 4 | + |
| 5 | +## Creating issues |
| 6 | + |
| 7 | +Whenever you happen upon something that needs improvement, be sure to come back to us and create an issue. Please make |
| 8 | +use of the available templates and answer all the included questions, so that the maintenance team can understand your |
| 9 | +problem easier. |
| 10 | + |
| 11 | +## Pull requests |
| 12 | + |
| 13 | +### Fork-Pull |
| 14 | + |
| 15 | +We accept external pull requests according to |
| 16 | +the [standard GitHub fork-pull flow](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). |
| 17 | +Create a fork of this repository, commit your changes there and create a pull request. We try to review those as often |
| 18 | +as possible. |
| 19 | + |
| 20 | +### Main & stable branches |
| 21 | + |
| 22 | +#### `main` |
| 23 | + |
| 24 | +All code changes should branch from [main](https://github.com/VirtusLab/scala-cli/tree/main) (which is also the default |
| 25 | +branch). |
| 26 | + |
| 27 | +#### `stable` and documentation changes |
| 28 | + |
| 29 | +However, documentation changes which don't depend on any not-yet-released code changes should branch |
| 30 | +from [stable](https://github.com/VirtusLab/scala-cli/tree/stable). This allows the CI to immediately update the website. |
| 31 | +A subsequent PR from `stable` back to `main` is created automatically. |
| 32 | + |
| 33 | +### Rules for a well-formed PR |
| 34 | + |
| 35 | +Whenever reasonable, we try to follow the following set of rules when merging code to the repository. Following those |
| 36 | +will save you from getting a load of comments and speed up the code review. |
| 37 | + |
| 38 | +- If the PR is meant to be merged as a single commit (`squash & merge`), please make sure that you modify only one |
| 39 | + thing. |
| 40 | + - This means such a PR shouldn't include code clean-up, a secondary feature or bug fix, just the single thing |
| 41 | + mentioned in the title. |
| 42 | + - If it's not obvious, please mention it in the PR description or a comment. |
| 43 | +- Otherwise, make sure you keep all the commits nice and tidy: |
| 44 | + - all side-refactors, nitpick changes, formatting fixes and other side-changes should be extracted to separate |
| 45 | + commits with the `NIT` prefix in the commit message; |
| 46 | + - similarly, code review comments regarding such changes should be marked with the same prefix; |
| 47 | + - ensure everything compiles at every commit (`./mill -i __.compile`); |
| 48 | + - ensure everything is well formatted at every commit (`scala-cli fmt .` or `scalafmt`); |
| 49 | + - ensure imports are well-ordered at every commit (`./mill -i __.fix`); |
| 50 | + - ensure reference docs are up-to date at every commit (`./mill -i generate-reference-doc.run`); |
| 51 | + - ensure all tests pass at every commit (refer to the [dev docs](DEV.md) on how to run tests); |
| 52 | + - nobody expects you to run all the unit and integration tests for all platforms locally, that'd take too long; |
| 53 | + - just make sure the test suites relevant to your changes pass on your local machine. |
| 54 | + |
| 55 | +Other notes: |
| 56 | + |
| 57 | +- give a short explanation on what the PR is meant to achieve in the description, unless covered by the PR title; |
| 58 | +- make sure to add tests wherever possible; |
| 59 | + - favor unit tests over integration tests where applicable; |
| 60 | +- try to add scaladocs for key classes and functions; |
| 61 | +- try to add comments where your code isn't self-explanatory; |
| 62 | +- if you're changing the app behaviour or adding a new feature, make sure to add docs on the website (or note in the PR |
| 63 | + that you'll do it separately). |
0 commit comments