Contributing.md

Contributing

I welcome any issues or PRs :)

Writing code

Running locally

1. Clone the repo
2. Install the relevant dependencies
   • VS Code Insiders (needed to run the tests from CLI, see using Insiders version for extension development)
   • Node 20, which comes automatically bundled with npm 8, another dependency.
3. npm i
4. Use bash to run the npm scripts. They use commands that are not compatible with PowerShell. Use this setting: "terminal.integrated.defaultProfile.windows": "Git Bash"

   If you use Command Prompt or PowerShell, you may see errors like

   'rm' is not recognized as an internal or external command, operable program or batch file.
   

Recommended VS Code settings

This repo enforces formatting, so it's recommended to format on save:

See language-specific editor settings

// settings.json - https://code.visualstudio.com/docs/getstarted/settings#_settingsjson
{
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "terminal.integrated.defaultProfile.windows": "Git Bash",
    "[ahk]": {
        "editor.defaultFormatter": "mark-wiemer.vscode-autohotkey-plus-plus",
    },
}

Test-driven development

To verify your fix worked as expected, we recommend following test-driven development

1. Identify a bug you'd like to fix
2. Write a test that fails with the current code due to that bug
3. Update the code to pass the test
4. Repeat the above process with more and more complex test cases
5. Clean up the code
6. Commit the code

This way, we'll alway have a test to ensure we don't re-introduce a bug

Writing Code FAQ

Validate the build

Please validate the build before opening a PR. Automated checks will have to pass before the PR can be merged.

1. npm run validate for automated checks
2. Go to Run and Debug viewlet (Ctrl+Shift+D) and click "Run Extension" for manual checks

Automated checks

All checks are found in 📄 package.json#scripts.

• Validate: Make sure everything is working correctly
  • Lint
    • TSC: TypeScript compiler checks for compile-time issues
    • ESLint: ESLint checks code quality
    • Format: Prettier checks code formatting
    • PackageJSON: sort-package-json checks package.json property order
  • Test
    • Pretest (compile)
      • TS: TypeScript compiler "upserts" .js files that are executed
      • Grammar: js-yaml converts language syntax from YAML to JSON
    • Automated tests: Mocha checks functionality

Syntax highlighting

The syntax in 📄 language/ahk.tmLanguage.yaml determines how syntax highlighting is applied.

; No syntax highlighting here 😞

; This comment is colored green thanks to syntax highlighting 🌈

Some resources:

• See the official syntax highlight guide for more details about how this works.
• We use PanAeon/vscode-tmgrammar-test for testing the grammar.
• If you're curious, microsoft/vscode-textmate hosts the tokenization grammar.

To update the syntax, we recommend following this flow:

1. 🤔 Take some time to reproduce a syntax highlighting issue with as little AHK code as possible
2. ➕ Add a new file in 📁 src/test/suite/grammar/samples that demonstrates the issue
3. 🏃 Run npm run test_grammar to generate a .snap snapshot for the file you added
4. ✏️ Edit the YAML grammar
5. 🧪 Repeat the last two steps until everything is working as you want

   PanAeon/vscode-tmgrammar-test has great documentation on how to test the syntax