Skip to content

Commit 6d34348

Browse files
tgodziktgodzik
authored
Merge pull request #1650 from Gedochao/tweak-readme
Decompose the README & add a contributing guide
2 parents 73ce01d + 2fb62f4 commit 6d34348

File tree

3 files changed

+316
-228
lines changed

3 files changed

+316
-228
lines changed

‎CONTRIBUTING.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
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).

‎DEV.md

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
## Developer docs
2+
3+
### Requirements
4+
5+
Building Scala CLI requires JVM 17 to work properly.
6+
7+
In theory, our build is able to download and install for its own needs JVM 17 on some OSes however it may not work in
8+
Intellij / Metals out of the box.
9+
10+
The Scala CLI sources ship with Mill launchers, so that Mill itself doesn't need to be installed on your system.
11+
12+
### Common commands
13+
14+
#### Running the CLI from sources
15+
16+
```bash
17+
./mill -i scala …arguments…
18+
```
19+
20+
#### Run unit tests
21+
22+
```bash
23+
./mill 'build-module.test'
24+
```
25+
26+
To can filter unit test suites:
27+
28+
```bash
29+
./mill 'build-module.test' 'scala.build.tests.BuildTestsScalac.*'
30+
./mill 'build-module.test' 'scala.build.tests.BuildTestsScalac.simple'
31+
```
32+
33+
#### Run integration tests with the JVM launcher
34+
35+
```bash
36+
./mill integration.test.jvm
37+
```
38+
39+
Filter test suites with
40+
41+
```bash
42+
./mill integration.test.jvm 'scala.cli.integration.RunTestsDefault.*'
43+
./mill integration.test.jvm 'scala.cli.integration.RunTestsDefault.Multiple scripts'
44+
```
45+
46+
You can pass the `--debug` option to debug Scala CLI when running integration tests. Note that this allows to debug the
47+
Scala CLI launcher (the app) and not the integration test code itself. The debugger is being run in the `attach` mode.
48+
49+
```bash
50+
./mill integration.test.jvm 'scala.cli.integration.RunTestsDefault.*' --debug
51+
```
52+
53+
The debug option uses 5005 port by default. It is possible to change it as follows:
54+
55+
```bash
56+
./mill integration.test.jvm 'scala.cli.integration.RunTestsDefault.*' --debug:5006
57+
```
58+
59+
#### Run integration tests with the native launcher
60+
61+
(generating the launcher can take several minutes)
62+
63+
```bash
64+
./mill integration.test.native
65+
./mill integration.test.native 'scala.cli.integration.RunTestsDefault.*'
66+
```
67+
68+
#### Generate native packages
69+
70+
Build native packagers:
71+
72+
* `deb` for linux
73+
* `msi` for windows
74+
* `dmg` and `pkg` for macOS
75+
76+
(generating native packager for specified format)
77+
78+
```bash
79+
./mill -i scala package ..arguments... --deb --output 'path.deb'
80+
./mill -i scala package ..arguments... --dmg --output 'path.dmg'
81+
./mill -i scala package ..arguments... --pkg --output 'path.pkg'
82+
```
83+
84+
#### IDE Import
85+
86+
The Scala CLI repository should work when imported automatically from Mill to IDEA IntelliJ and Metals.
87+
Please raise an issue if you run into any problems.
88+
89+
#### Generate a native launcher
90+
91+
```bash
92+
./mill -i show cli.nativeImage
93+
```
94+
95+
This prints the path to the generated native image.
96+
The file named `scala` at the root of the project should also
97+
be a link to it. (Note that the link is committed and is always there,
98+
whether the files it points at exists or not.)
99+
100+
#### Generate a JVM launcher
101+
102+
```bash
103+
./mill -i show cli.launcher
104+
```
105+
106+
This prints the path to the generated launcher. This launcher is a JAR,
107+
that directly re-uses the class directories of the modules of the project
108+
(so that cleaning up those classes will break the launcher). If this is a
109+
problem (if you wish to run the launcher on another machine or from a
110+
Docker image for example), use a native launcher (see above) or a standalone
111+
JVM one (see below).
112+
113+
#### Generate a standalone JVM launcher
114+
115+
```bash
116+
./mill -i show cli.standaloneLauncher
117+
```
118+
119+
This prints the path to the generated launcher. This launcher is a JAR,
120+
that embeds JARs of the scala-cli modules, and downloads their dependencies
121+
from Maven Central upon first launch (using the coursier cache, just like
122+
a coursier bootstrap).
123+
124+
### Helper projects
125+
126+
A number of features of Scala CLI are managed from external projects, living under
127+
the [`scala-cli` organization](https://github.com/scala-cli) on GitHub. These
128+
projects can be used by Scala CLI as libraries pulled before it's compiled, but also
129+
as binaries. In the latter case, Scala CLI downloads on-the-fly binaries from these
130+
repositories' GitHub release assets, and runs them as external processes.
131+
132+
For example, here are a few external projects used by Scala CLI:
133+
134+
- [scala-js-cli-native-image](https://github.com/scala-cli/scala-js-cli-native-image): provides a binary running the
135+
Scala.js linker
136+
- [scala-cli-signing](https://github.com/scala-cli/scala-cli-signing): provides both libraries and binaries to handle
137+
PGP concerns in Scala CLI
138+
- [libsodiumjni](https://github.com/scala-cli/libsodiumjni): provides minimal JNI bindings for
139+
[libsodium](https://github.com/jedisct1/libsodium), that is used by Scala CLI to encrypt secrets
140+
uploaded as GitHub repository secrets in the `publish setup` sub-command
141+
142+
For the full list of those projects and their description, see the
143+
[scala-cli repository list](https://github.com/orgs/scala-cli/repositories) and the READMEs
144+
of each of these projects.
145+
146+
The use of external binaries allows to make the Scala CLI binary slimmer and faster
147+
to generate, but also allow to lower memory requirements to generate it (allowing to
148+
generate these binaries on the GitHub-provided GitHub actions hosts).
149+
150+
### Website
151+
152+
The Scala CLI website is built with [Docusaurus](https://v1.docusaurus.io/en/) and
153+
uses [Infima](https://infima.dev/docs/layout/spacing) for styling.
154+
155+
Ensure you are using Node >= 16.14.2.
156+
157+
#### Generate the website once
158+
159+
```bash
160+
cd website
161+
yarn
162+
yarn build
163+
npm run serve
164+
```
165+
166+
#### Generate the website continuously
167+
168+
```bash
169+
cd website
170+
yarn
171+
yarn run start
172+
```
173+
174+
### Verifying the documentation
175+
176+
We have a built-in tool to validate `.md` files called [Sclicheck](/sclicheck/Readme.md).
177+
All `Sclicheck` tests can be run with `Mill` + `munit`: (and this is what we run on the CI, too)
178+
179+
```bash
180+
./mill -i docs-tests.test
181+
```
182+
183+
The former also includes testing gifs and `Sclicheck` itself.
184+
To just check the documents, run:
185+
186+
```bash
187+
./mill -i docs-tests.test 'sclicheck.DocTests.*'
188+
```
189+
190+
You can also check all root docs, commands, reference docs, guides or cookbooks:
191+
192+
```bash
193+
./mill -i docs-tests.test 'sclicheck.DocTests.root*'
194+
./mill -i docs-tests.test 'sclicheck.DocTests.guide*'
195+
./mill -i docs-tests.test 'sclicheck.DocTests.command*'
196+
./mill -i docs-tests.test 'sclicheck.DocTests.cookbook*'
197+
./mill -i docs-tests.test 'sclicheck.DocTests.reference*'
198+
```
199+
200+
Similarly, you can check single files:
201+
202+
```bash
203+
./mill -i docs-tests.test 'sclicheck.DocTests.<category> <doc-name>'
204+
```
205+
206+
For example, to run the check on `compile.md`
207+
208+
```bash
209+
./mill -i docs-tests.test 'sclicheck.DocTests.command compile'
210+
```
211+
212+
## Scala CLI logos
213+
214+
Package with various logos for scala-cli can be found
215+
on [google drive](https://drive.google.com/drive/u/1/folders/1M6JeQXmO4DTBeRBKAFJ5HH2p_hbfQnqS)
216+
217+
## Launcher script
218+
219+
There is a script `scala-cli-src` in the repository root that is intended to work exactly like released scala-cli, but
220+
using a binary compiled the worktree.
221+
Just add it to your PATH to get the already-released-scala-cli experience.
222+
223+
## Releases
224+
225+
Instructions on how to
226+
release - [Release Procedure](https://github.com/VirtusLab/scala-cli/blob/main/.github/release/release-procedure.md)
227+
228+
## Debugging BSP server
229+
230+
The easiest way to debug BSP sever is using `scala-cli-src` script with `--bsp-debug-port 5050` flag (the port should be
231+
unique to the workspace where BSP will be debugged). In such case BSP will be launched using local source and will run
232+
on JVM. It will also expects a debugger running in the listen mode using provided port (so the initialization of the
233+
connection can be debugged). In such case we recommend to have option to auto rerun debugging session off (so there is
234+
always a debugger instance ready to be used).

0 commit comments

Comments
 (0)