diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 255a9431b..bb61ca9f7 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -16,6 +16,7 @@ When creating a new bug report do: ### Improve Existing Issues +- Try to replicate bugs and describe the method if you're able to. - Search for [duplicate issues](https://github.com/VSCodeVim/Vim/issues?q=is%3Aissue+is%3Aopen+cursor). See which thread(s) are more mature, and recommend the duplicate be closed, or just provide links to related issues. - Find [old issues](https://github.com/VSCodeVim/Vim/issues?page=25&q=is%3Aissue+is%3Aopen) and test them in the latest version of VSCodeVim. If the issue has been resolved, comment & recommend OP to close (or provide more information if not resolved). - Give thumbs up / thumbs down to existing issues, to indicate your support (or not) @@ -29,40 +30,60 @@ When submitting a PR, please fill out the template that is presented by GitHub w ## First Time Setup -1. Install prerequisites: - - latest [Visual Studio Code](https://code.visualstudio.com/) - - [Node.js](https://nodejs.org/) v12.0.0 or higher - - [Yarn](https://classic.yarnpkg.com/) v1.x - - _Optional_: [Docker Community Edition](https://store.docker.com/search?type=edition&offering=community) 🐋 -1. In a terminal: +1. Install prerequisites: - ```bash - # fork and clone the repository - git clone git@github.com:/Vim.git - cd Vim + - [Visual Studio Code](https://code.visualstudio.com/), latest stable or insiders + - [Node.js](https://nodejs.org/) v14.0.0 or higher + - [Yarn](https://classic.yarnpkg.com/) v1.x + - _Optional_: [Docker Community Edition](https://store.docker.com/search?type=edition&offering=community) 🐋 - # Install the dependencies - yarn install +2. Fork and clone repository: - # Open in VSCode - code . + ```bash + git clone git@github.com:/Vim.git + cd Vim + ``` - # Choose the "Build, Run Extension" in the dropdown of VSCode's - # debug tab to build and run the extension. - # Or run tests by selecting the appropriate drop down option +3. Build extension: - # Alternatively, build and run tests through gulp and npm scripts - npx gulp build # build - npx gulp prepare-test # build tests - yarn test # test (must close all instances of VSCode) + ```bash + # Install the dependencies + yarn install - # Only available if Docker is installed and running - npx gulp test # run tests inside Docker container - npx gulp test --grep testSuite # run only tests/suites filtered by js regex inside container + # Open in VS Code + code . - # Alternatively, build .vsix extension and load it into VSCode for manual testing - yarn run vsce package # build vim-xxx.vsix - ``` + # Build with one of these... + npx gulp build-dev # Fast build for development + npx gulp build # Slow build for release + yarn watch # Fast build whenever a file changes + ``` + +4. Run extension using VS Code's "Run and Debug" menu + +5. Run tests: + + ```bash + # If Docker is installed and running: + npx gulp test # Run tests inside Docker container + npx gulp test --grep # Run only tests/suites matching inside Docker container + + # Otherwise, build and run the tests locally: + npx gulp build # Build + npx gulp prepare-test # Build tests + yarn test # Test (must close all instances of VS Code) + ``` + +6. Package and install extension: + + ```bash + # Package extension into `vim-...vsix` + # (This can be opened and inspected like a .zip file) + yarn run vsce package --yarn + + # Install packaged extension to your local VS Code installation + code --install-extension vim-...vsix --force + ``` ## Code Architecture @@ -90,12 +111,12 @@ Consists of two data structures: #### How it works -1. `handleKeyEventHelper` is called with the most recent keypress. -2. `Actions.getRelevantAction` determines if all the keys pressed so far uniquely specify any action in actions.ts. If not, we continue waiting for keypresses. -3. `runAction` runs the action that was matched. Movements, Commands and Operators all have separate functions that dictate how to run them - `executeMovement`, `handleCommand`, and `executeOperator` respectively. -4. Now that we've updated VimState, we run `updateView` with the new VimState to "redraw" VSCode to the new state. +1. `handleKeyEventHelper` is called with the most recent keypress. +2. `Actions.getRelevantAction` determines if all the keys pressed so far uniquely specify any action in actions.ts. If not, we continue waiting for keypresses. +3. `runAction` runs the action that was matched. Movements, Commands and Operators all have separate functions that dictate how to run them - `executeMovement`, `handleCommand`, and `executeOperator` respectively. +4. Now that we've updated `VimState`, we run `updateView` with the new VimState to "redraw" VS Code to the new state. -#### vscode.window.onDidChangeTextEditorSelection +#### `vscode.window.onDidChangeTextEditorSelection` This is my hack to simulate a click event based API in an IDE that doesn't have them (yet?). I check the selection that just came in to see if it's the same as what I thought I previously set the selection to the last time the state machine updated. If it's not, the user _probably_ clicked. (But she also could have tab completed!) @@ -110,23 +131,23 @@ git push --follow-tags The above Gulp command will: -1. Bump the package version based off the semver supplied. Supported values: patch, minor, major. -2. Create a changelog using [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator). -3. Create a Git commit with the above changes. -4. Create a Git tag using the new package version. +1. Bump the package version based off the semver supplied. Supported values: patch, minor, major. +2. Create a changelog using [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator). +3. Create a Git commit with the above changes. +4. Create a Git tag using the new package version. In addition to building and testing the extension, when a tag is applied to the commit, the CI server will also create a GitHub release and publish the new version to the Visual Studio marketplace. ## Troubleshooting -### Visual Studio Code Slowdown +### VS Code Slowdown If you notice a slowdown and have ever run `yarn test` in the past instead of running tests through VSCode, you might find a `.vscode-test/` folder, which VSCode is continually consuming CPU cycles to index. Long story short, you can speed up VSCode by: ```bash -$ rm -rf .vscode-test/ +rm -rf .vscode-test/ ``` -## Styleguide +## Style Guide Please try your best to adhere to our [style guidelines](https://github.com/VSCodeVim/Vim/blob/master/STYLE.md). diff --git a/STYLE.md b/STYLE.md index e32d8b5c1..b1435986a 100644 --- a/STYLE.md +++ b/STYLE.md @@ -1,31 +1,18 @@ -## Style Guide +# Style Guide -In addition, to VS Code's [coding guidelines](https://github.com/Microsoft/vscode/wiki/Coding-Guidelines), please adhere to the following: +In addition, to VS Code's [coding guidelines](https://github.com/Microsoft/vscode/wiki/Coding-Guidelines), please adhere +to the following: - Use `for ... of` whenever possible **Rationale:** `for ... of` is awesome. It's more readable than any other variant. -- Don't use `any` as much as possible +- Do not use `any` except when necessary - **Rationale:** The language is called *Type*Script, not *Untyped*Script. :wink: Static typing is wonderful. It catches bugs and improves readability. We should strive to use it as much as possible. + **Rationale:** The language is called *Type*Script, not *Untyped*Script. :wink: Static typing is wonderful. + It catches bugs and improves readability. We should strive to use it as much as possible. - Use `const` wherever possible. - **Rationale:** Instead of reading `const` as "constant value," read it as "single assignment." Yes, it means "constant value" in other programming languages, but it's a little different in JavaScript. - -- When we can't use `const`, use `let`; never `var` - - **Rationale:** `var` trips up programmers in a number of cases - hoisting and closure capture are two big ones. Consider the difference between - - ``` - for (var j = 0; j < 5; j++) { setTimeout(() => console.log(j), 5) } - ``` - - and - - ``` - for (let j = 0; j < 5; j++) { setTimeout(() => console.log(j), 5) } - ``` - - Even if you're not capturing the variable, who knows if someone else might later? + **Rationale:** Instead of reading `const` as "constant value," read it as "single assignment." + Yes, it means "constant value" in other programming languages, but it's a little different in JavaScript.