Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
96 lines (66 loc) · 4.67 KB

CONTRIBUTING.md

File metadata and controls

96 lines (66 loc) · 4.67 KB

Ways to Contribute

🐛 Bugs & 🤔 Ideas

Feel free to open an issue to report a bug or share us your great ideas!

Please only put one bug/suggestion in each issue to make it easier to track, and provide helpful information (like the commands you wrote, the errors it showed) to help reproduce and fix.

🌐 Translation

Localization status

Spyglass supports multiple languages. If you'd like to help us translate this project to your language, it would be really appreciated!

Steps

  1. Go to the localization website.
  2. Register by linking your GitHub account (recommended), or using your email.
  3. See two components of Spyglass here.
  4. Start translating!

Note

  • If your language is not listed on the platform, simply open an issue.
  • If you have suggestions for the source string (en-us), please open an issue, or discuss with other translators at the Discord server if you'd like to.

💰 Sponsor

Some team members accept donations. If you're interested in sponsoring, you can go to their GitHub Sponsors pages:

💻 Developing

  1.  $ git clone https://github.com/SpyglassMC/Spyglass.git
  2. Install Node.js LTS.
  3.  $ npm i && npm run build

If you're using VS Code to develop Spyglass:

  • Install the recommended ESLint extension. Make a copy of .vscode/settings.template.json and rename it to .vscode/settings.json. Now your VS Code should automatically fix all linting errors every time you save the file.
  • Press F5 to run the VS Code extension in development environment (Server + Client). VS Code will automatically compile all packages and build the extension file in watch mode.

Or if you prefer the command line interface:

  • npm run build to build all packages.
  • npm run watch to watch changes and build all packages.
  • npm run clean to remove all js output. Use this when there seem to be caching issues with TypeScript's compiler.
  • npm test to test all packages.
  • npm run test:update-snapshots to run tests and update test snapshots.
  • npm run test:watch to run tests in watch mode.
  • npm run fmt to format all files.
  • npm run lint to check linting errors.
  • npm run lint:fix to fix all auto-fixable linting errors.
  • npm run commit to run the gitmoji CLI. You actually don't have to worry about commit message as long as you're creating PR, as I can always change it.

You can debug tests with breakpoints by running the Run Unit Tests configuration and setting your breakpoints accordingly. If you want to run a specific subset of tests, add .only or { only: true} after the test block (e.g. describe.only(), it.only(), it('...', { only: true }, ...)).

Note that the lint will fail in CI/CD if only tests are pushed to prevent mistakenly merging only to main (it should only be used for local testing!).

Code style

Tabs for indents, spaces for alignment. Except do not align things because the available tooling is unfortunately terrible.

Test docs locally

  1. Install Jekyll according to its documentation.
  2. Run npm run docs:start to start a local preview at localhost:4000.

Build Pipeline

The build script at the root level does the following steps in series:

  • Run the build script in ./packages/locales.
  • Run the TypeScript compiler across all packages.
  • Then, do the two steps in parallel:
    1. Run the build script in ./packages/playground.
    2. Run the build script in ./packages/vscode-extension.

Module system

The whole Spyglass project, including its source code and output, uses ES module. However, as VS Code cannot consume ES modules as extensions (microsoft/vscode#130367), the vscode-extension package defaults to use CommonJS modules, with file extensions mjs and mts to explicitly override that,