First of all, we'd like to thank you for taking some of your time to contribute to the project. You're awesome 🤠👍
Architecture decisions for this project are documented here, using the Architecture Decision Records (ADR) pattern.
- Getting started
- Run the tests
- Create a new refactoring
- Useful resources to start changing the code
- Code Style
- Debug locally
- Create a package and use it
- Open a PR and add acknowledge your contribution
- Clone the repo:
git clone [email protected]:nicoespeon/abracadabra.git - Go into the cloned repository:
cd abracadabra - Install dependencies:
yarn install
The project uses TypeScript, Jest for the tests and Prettier for the formatting.
You can run tests with yarn test.
To run tests in watch mode, use yarn test --watch.
We use Jest under the hood, so you can pass any valid Jest command to yarn test.
In short, most of our tests are unit tests. We test business logic in isolation from VS Code API.
We don't have VS Code integration tests. We've documented why in this ADR.
Run yarn new and follow the tool, it will ask you the relevant questions.
We've documented the context of this decision in this ADR.
If you want to change how code scaffolding works, check hygen documentation.
- VS Code Extension API documentation is a good start
- AST Explorer is a very handy tool to explore the AST. Use
babylon-7parser. - As we use Babel to transform the AST, the handbook is very useful. In particular the transformation and the manipulation parts.
Style formatting is managed by Prettier. It runs as a pre-commit hook, so you shouldn't have to worry about it 👐
There a few conventions that we'd like to keep consistent and are not automatically enforced yet.
We structure TS files like this:
// 1. Imports from external libs
import { parse } from "@babel/parser";
// 2. Imports from local files
import { Selection } from "./selection";
import { Position } from "./position";
// 3. Exports
export { isStringLiteral, isClassDeclaration };
export { StringLiteral };
// 4. Rest of the code
function isStringLiteral() {
// …
}As a general rule, we prefer to have what is exposed appear before what is private. That's why we list the exports at the top of the file. We find it simpler to see what is exposed from a file, so it's easier to decide if that's too much and we should split.
You can use VS Code's built-in debugger on the project to test the extension.
To build the project, press F5.
It will open an "Extension Development Host" window, overriding your "Abracadabra" extension with your local code. This is helpful to test your changes in integration with VS Code API.
If you do changes, rebuild the project by clicking on the reload icon.
While debugging the extension is helpful to see changes in action, you can use the unit tests to develop without having to rebuild the project at every change.
To create a package from your local code, run yarn package.
When it's done, run yarn package:install to install this new version instead of the one you had.
This allows you to use the package before it's published to the MarketPlace.
You can open a Pull-Request at any time. It can even be a draft if you need to ask for guidance and help. Actually, we'd be pretty happy to assist you going in the best direction!
Once everything is ready, open a Pull-Request (if it's not already done) and ask for a review. We'll do our best to review it asap.
Finally, use all-contributors bot command to add yourself to the list of contributors. It's very easy to do, you basically need to mention the bot in a comment of your PR.
Whether it's code, design, typo or documentation, every contribution is welcomed! So again, thank you very, very much 🧙