Calva is mostly TypeScript, but some things are written in ClojureScript. The cljs code is compiled by
shadow-cljs into a
:node-library, that is then required from TypeScript.
Start by saying hello in #calva at the Clojurians Slack. Then:
devbranch. This is where all Calva development happens.
The dev process looks like so:
:calva-lib, and run its tests
About waiting for the build to complete.
Currently when jacking into Calva, when you start the
:calva-libbuild then also select the same build to connect to before the terminal shows that the shadow build completed, then open the extension host, things do not work, like evaluation. If you wait for the build to show completed in the terminal before selecting
:calva-libto connect to in the prompt, then open the extension host, things work as expected.
Calva has four bodies of automatic testing, all of which are run as part of the Calva CI pipeline:
While developing, the
calva-lib tests are run automatically as part of the watcher process. You only need to be concerned with the grammar tests if you are hacking on the grammar. We haven't written about how to run those, it involves using Atom, contact us and we'll show you.
You can run the TS unit tests in (at least) two ways:
npm run unit-test.
It is recommended you use both methods.
The coverage is slim so far. Please consider helping the Calva project by adding test suites and adding to the existing ones.
These are just a stub right now. Please help in adding some meaningful tests.
Running the integration tests is done from the command line
npm run integration-test. However, you need to not have VS Code running when you do it.
Calva has two sets of grammars.
The tmLanguage Clojure grammar originated in Atom and still needs Atom for the automated testing:
You probably need to update the specs too, depending on the change. Consider writing a test that catches if your change to the grammar would be removed.
For actually making the grammar work in VS Code, you need to convert the CSON grammar file to JSON:
npm run update-grammar. This updates the
clojure.tmLanguage.jsonfile used by VS Code.
Please don't hesitate to holler at @pez on the Clojurians slack.
If you're making changes to the docs that are not associated with code changes, make the changes on the
master branch. If you're making doc changes associated with code changes, make them on the branch that contains the code changes.
Install MkDocs + Material. From the Calva directory, run:
pip install -r requirements.txt
(Or your preferred method from https://squidfunk.github.io/mkdocs-material/getting-started/)
If you get an error with the pip install method above, you may have an older version of python. If you install python 3.7 and run the following command, it should work:
python3.7 -m pip install -r requirements.txt
Run the MkDocs server:
Edit docs. It's all Markdown. When you save, the changes will be reloaded in the browser.
Note: The MkDocs Markdown is a bit pickier than GitHub's, so make sure to use four indents, put an empty line before bulleted lists, and so on. The VS Code extension markdownlint helps with following the appropriate style. And make sure to check the results at your local site.
Feel invited to send us a PR just as a way to get feedback. You don't need to wait until your code works or the change is completed. Work in progress is totally PR-able.
Make sure you are directing the pull request at the
dev branch, unless you have reasons to target some other branch. Also, ”some other branch” is never
master, which happens to be the default.
[Unreleased]. Link your entry to the issue you are fixing.
Please also see:
When you have issued your pull request, it is best to ping us about it to catch our attention. The #calva channel of the Clojurians Slack is a good place for this ping, mention
We will try to get back to you quickly with our assessment of whether this PR fits the Calva path. Depending on the nature of the change it might need some discussion.
We use Circle-CI to automatically build any updates to a PR. It will run the automated tests and give you feedback on the PR page on Github. It will also build a VSIX package for you. Every time you have pushed updates to the PR, please download it and smoke test it some. Our release process relies on that the VSIX packages are sanity checked along the development process. See [[Testing VSIX Packages]].
README.mdare done (or, if you prefer we write it, communicated to us).
Again, see the Pull Request Template for more.
See also: [[Testing VSIX Packages]]
Happy Calva Hacking! ❤️