A wonderful way to help the Joyride project is to be part of spreading the word about it. Please consider blogging, tweeting, publishing video content, etcetera, about this way to configure VS Code.
If you want to contribute to the quality and/or feature set of Joyride, helping us identify room for improvement is very welcome! If you want to contribute code, that is also highly appreciated. Please read below how we approach improvements to Joyride.
Before writing any code, please create an issue first that describes the problem you are trying to solve with alternatives that you have considered. A little bit of prior communication can save a lot of time on coding. Keep the problem as small as possible. If there are two problems, make two issues. When we collectively agree on the problem and solution direction, it's time to move on to a PR.
If the problem statement isn't clear, it's better to start with a Discussion.
Follow up with a pull request Post a corresponding PR with the smallest change possible to address the issue. Then we discuss the PR, make changes as needed and if we reach an agreement, the PR will be merged.
Please do not use git push --force on your PR branch for the following reasons:
- It makes it more difficult for others to contribute to your branch if needed.
- It makes it harder to review incremental commits.
- Links (in e.g. e-mails and notifications) go stale and you're confronted with: this code isn't here anymore, when clicking on them.
- Your PR will be squashed anyway.
Each bug fix, change or new feature should be tested well to prevent future regressions. Tests should be added to vscode-test-runner/workspace-1/.joyride/src/integration_test
We use @vscode/test-electron configured to spawn VS Code Insiders and run the tests in there. The test runner is written using Joyride.
Run the tests from the command line like so:
- Build the extension (as per the Development instructions)
npm run integration-test
This will download VS Code Insiders, start it, run the tests and then close VS Code Insiders. (If some test results in an error, VS Code Insiders might be left hanging. You then need to force quit it.)
You can also run tests from the development extension host. However, the test suite is designed to run with a special environment, to give it control over the user script content. This environment is set as part of the test run when run from the command line. If you run the tests from the REPL, some of them might not work, and some of them might even mess with your user scripts content. It's our recommendation to only run specific tests from the REPL and to use the command line for the full suite.
We assume you are using Calva.
npm i- In VS Code, Tasks: Run Build Task: cmd/ctrl+shift+b.
- This starts the nREPL server
- Wait for shadow-cljs to signal that building is done.
- Start the extension in debug mode: F5
- This starts the Extension Development Host
- In the extension development host, issue the command Calva: Start Joyride REPL and Connect
- Back in the Joyride project window: Connect the REPL to the nREPL server and the shadow-cljs build
:extension
When the Joyride project directory is open in VS Code, you will recognize this window by it's title bar, and the default Extension Development Host window is also recognizable this way.
In this screenshot the Joyride project window, with a Joyride-red title bar, is behind the extension development host window, with a Joyride-yellow title bar. (The status bar of the Joyride window is also red, because VS Code highlights it for being the window where the debug session is spawned and controlled from. It might be some other color on your machine, depending on what theme you use.)
You will have two REPLs.
- One REPL in the Joyride project window
- For developing Joyride itself.
- This is a shadow-cljs REPL and the Joyride extension will hot reload as you save files (or you can just load changes in the REPL to update the extension).
- Another REPL in the Extension Development Host window
- This is the REPL of your Joyride under development.
- This REPL will not hot reload anything based on files saved, you'll have to load changes in the REPL manually.
By default, the debug extension host session opens up the integration testing project, which is part of this repository/project. (See Tests for more on the tests.) This makes it easy to test Joyride with relevant sample content, manually, or via integration test code. It also means that content you create or change there can be committed back to the repository. Please note that we want any Joyride content in this integration test project's script and src directories to be consumed by integration tests, so if you think some content should be added, please also add integration tests for it.
Please let us know how the development process works for you.
A great place to discuss Joyride development things is in the #joyride channel at the Clojurians Slack.
Happy contributing! ❤️🙏