The code in this repository is primarily divided into three top-level directories:
scalameta/: syntactic APIs like tokenizers, parsers, trees, quasiquotes and pretty printers.
semanticdb/: semantic APIs like the SemanticDB protobuf schema, compiler plugin, metacp to process classpaths and metap to pretty-print SemanticDB payloads.
tests/: unit and integration tests for both Scalameta and SemanticDB.
The exact test command to run tests depends on what you are working on:
testsJVM/test: run fast unit tests for both syntactic and semantic APIs.
testsJVM/slow:test: run slow integration tests for semantic APIs.
testsJVM/all:test: run all tests, both fast and slow.
Tips to make your edit/test/debug worflow as productive as possible:
testOnlyto speedup your workflow. Running
testsJVM/testmay still be too slow if you want fast feedback while iterating on a small change. It's recommended to use
CUSTOM_SUITEis the name of your test suite.
testOnly *CUSTOM_SUITE -- -z "TEST_NAME"to target an individual test case from a test suite. Some test suites contains a lot of unit tests so it may still be too slow to use
testOnly. To target an individual slow test you must use the
testsJVM/all:testOnly *CUSTOM_SUITE -- -z "TEST_NAME".
- Use the sbt command
ExpectSuitepass. This command writes to disk the output of the current behavior. The diff may be large, please review it thoroughly to ensure that the new expected behavior is correct. The name "expect tests" comes from this blog post.
- Contain steps to reproduce.
- Contain a code sample that exhibits the error.
- Ideally contain your scalameta/semanticdb versions.
- Ideally contain the scala version you are using.
- Inform us if the issue is blocking you with no visible workaround
- This will give the ticket priority
- Show a code example of how that feature would be used.
- All code PRs should:
- have a meaningful commit message description
- comment important things
- include unit tests (positive and negative)
- pass CI, which automatically runs when your pull request is submitted.
- be reformatted with
- Be prepared to discuss/argue-for your changes if you want them merged! You will probably need to refactor so your changes fit into the larger codebase
- If your code is hard to unit test, and you don't want to unit test it, that's ok. But be prepared to argue why that's the case!
- It's entirely possible your changes won't be merged, or will get ripped out later. This is also the case for maintainer changes, even @xeno-by!
- Even a rejected/reverted PR is valuable! It helps explore the solution space, and know what works and what doesn't. For every line in the repo, at least three lines were tried, committed, and reverted/refactored, and more than 10 were tried without committing.
- Feel free to send Proof-Of-Concept PRs that you don't intend to get merged.
- Sign the Scala CLA. Signed CLA is necessary to merge your PR.
- Prefer the terms
extensionas opposed to
In case of any questions, don't hesitate to ask on our gitter channel.
(these guidelines have been adapted from https://github.com/lihaoyi/ammonite#contribution-guidelines)