Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
81 lines (64 loc) · 5.34 KB

CONTRIBUTING.md

File metadata and controls

81 lines (64 loc) · 5.34 KB

Contributing

Repository tour

  • .vscode/ contains files for VSCode development.
    • launch.json defines launch tasks for debugging.
    • settings.json defines project-level settings.
  • grammars/ contains generated grammars. Do not modify these files by-hand; they will be over-written.
  • icons/ contains file icons and the original extension icon SVG. The file icons are not currently used by the extension due to limitations with the VSCode theming API.
  • lib/ contains all of the interesting stuff, and most of what you'll probably care about.
    • out/ is where compiled output typically goes. You can safely ignore folders like this.
    • src/ contains all of the library TypeScript source code to be compiled into JavaScript.
      • grammars/ contains grammar stubs used as a basis for generated grammars.
        • version-agnostic.yaml is the version-agnostic grammar, in a custom format.
        • version-specific-base.yaml is the base grammar, common to all version-specific grammars.
      • cli.ts is the entry point for the grammar generator's command-line interface.
      • command-manifest.ts defines data structures for the server-generated commands.json.
      • language-grammar.ts defines data structures for various tmLanguage constructs.
      • utils.ts contains common utilities.
      • version-specific.ts contains the bulk of the version-specific grammar generator.
    • tsconfig.json is the configuration file for the TypeScript compiler.
  • tests/ contains all of the sample mcfunction files for testing. It is recommend that you add to the tests when fixing bugs or adding new features.
  • .vscodeignore lists the files/folders that need not be packaged with the extension. Everything in lib and tests is already listed here, but if you add new files elsewhere you should consider listing them in this file.
  • CHANGELOG.md lists changes from version to version, via the Keep a Changelog format.
  • CONTRIBUTING.md describes itself in one sentence.
  • icon.png is the extension icon.
  • language-configuration.json defines the language configuration for the VSCode extension.
  • LICENSE contains the license in plain-text.
  • mcfunction.tmLanguage(.json|.yaml) are generated files that exist in the project root to support other editors like SublimeText, without further configuration.
  • mcfunction.tmPreferences basically just defines comment formatting for SublimeText and other editors that support the tmLanguage format.
  • package-lock.json is a file generated by npm. No need to touch this one.
  • package.json defines the package attributes, such as name, version, and dependencies. Generally you shouldn't need to change this unless you're adding a new feature or language definition.
  • README.md describes the project and extension in detail.

Getting started

  1. Make sure you have Node.js and npm installed and ready to go.
  2. Clone a copy of the project to your development environment.
  3. Change into the project directory and run npm install to install dependencies.
  4. Attempt to debug the extension to ensure you have things in working order.
  5. Otherwise, feel free to post an issue and we'll do our best to help.

Development and debugging

We recommend using VSCode to develop and test the VSCode extension. Otherwise you're welcome to use whichever editor you prefer. In any case, please do your best to follow the style guide.

Debugging the extension

  1. Press F5 to launch an extension development host for debugging.
  2. Make changes in your main VSCode development window.
  3. Compile the grammars.
  4. Press Ctrl+R in the extension development host to reload the window and test your changes.
  5. At the moment we are testing the syntax highlighter just by scanning over relevant mcfunction files in tests/, but a more rigorous testing procedure may be implemented in the future.

Compiling the grammars

The following command will both compile lib (from TypeScript into JavaScript) and run the cli script to generate the version-agnostic grammar from version-agnostic.yaml:

npm run cli build-grammar

Providing two additional arguments: (1) a directory (the server-generated data folder) and (2) a version label; will cause the script to instead build a data dump for a particular version of the game. This data can in turn be used to generate a version-specific grammar based on version-specific-base.yaml:

npm run cli build-data ./generated/ snapshot
npm run cli build-grammar snapshot

I recommend creating a symlink generated (pre-configured in .gitignore) in the repository root that points to the generated data folder of a recent Minecraft snapshot. This will make it easier to supply the grammar generator with a directory for the server-generated data.

Style guide

  • We use prettier to auto-format our TypeScript code.