CONTRIBUTING.md

Contributing

Dance welcomes contributions!

Rules

Style

Unfortunately, the codebase is currently not automatically formatted, as it was made by following rules not currently enforced by any large formatter / style guide (please prove me wrong).

When editing files, please overall match the style of the surrounding code, and do not reformat the whole file on save. A couple of rules:

1. Comments should generally end at column 80, code at column 100.

2. Use double quotes, explicit semicolons, and trailing commas whenever possible.

Dependencies

In order to support building in some environments, cycles in the dependency graph are forbidden, which is enforced by .dependency-cruiser.js. This file also enforces a couple of other rules to keep the codebase tidy and predictable (e.g. the API of Dance may not depend on its commands).

Type-checking

Dance uses TypeScript, and must type-check.

Development

The recommended way to work on Dance is to run Launch extension or Launch extension with Helix keybindings in the "Run and Debug" view. This will run VS Code with the local version of Dance with a debugger attached.

The extension can also be built locally with yarn run package:pre or yarn run package-helix:pre, and then installed by right-clicking on the .vsix file.

Code generation

Many files in Dance are automatically generated to reduce the development burden:

• Files which end with .build.ts yield a file with the same name in the same directory.

  Details

  • package.build.ts generates package.json, and similarly for the Helix extension.

  • src/api/data/commands.build.ts generates the .yaml files in src/api/data.

  • src/commands/README.build.ts generates src/commands/README.md and layouts in src/commands/layouts. In order to avoid parsing commands again (which is already done by src/api/data/commands.build.ts), it defines a dependency on the files generated by src/api/data/commands.build.ts and reads them once they are available.

  • src/commands/load-all.build.ts reads files in src/commands/*.ts and generates src/commands/load-all.ts, which is used by Dance to define all commands when it loads based on their names and alternatives.

• Tests are generated from documentation comments and test Markdown files. See test/README.md for more information.

• Layouts in src/commands/layouts are generated from command information.

In VS Code, this code generation is automatically configured via tasks.json. CI will check that files are up-to-date in sent PRs.

Generally, src/api is the source of truth for APIs exposed by Dance, whereas src/commands is the source of truth for available commands and key bindings. In some cases (e.g. configuration, modes, and menus), package.build.ts files should be modified directly.

This whole logic is implemented in meta.ts. .build.ts files must export a function build() which either returns a string or a map from file name to generated content.

Commits

PRs should target master, and will be automatically checked. To ease reviewing in GitHub, pushing additional commits is encouraged over amending existing ones. PRs will be squashed to keep the master history clean.

Tests

New APIs, commands, and bug fixes should additionally have a new test. See the test directory for more information.

Wiki

Dance has a wiki. Unlike the Dance documentation, anyone can contribute to the wiki without going through a PR. Fairly common (but "non-official") key bindings, menus, and tips can be shared there.

Features

If you'd like to add or improve a feature, please make sure that no similar feature has been requested in the issues and file a new issue for it. This will ensure that no two people work on the same feature at the same time, and will be a good place to ask for help in case you want to tackle this yourself.
Since some features are not general enough, it may be requested of you to make a plugin that uses the Dance API or to simply use scripts in the meantime.

Misc.

Pre-release versions follow the pattern <major>.<minor>.<prev-patch><pre-release>, so for instance pre-release 1 of version 0.5.13 is 0.5.12001.

The reason for this convoluted strategy is that VS Code always installs the latest version; by making all patch versions of pre-release versions high, we make sure that they take precedence over release versions.

Delays

I, @71, the creator of Dance, have several times in the past not reviewed PRs for several months at a time. I'm trying to do better now, but can't guarantee I will always respond promptly. Notably, it may easily take more than a week for me to review code.

With that said, I'm open to granting to some maintainers the permission to accept PRs, push new versions, and otherwise maintain Dance with me. If you've submitted several PRs, are comfortable with the codebase, and would like to help, please contact me!