mirror of
https://github.com/VSCodeVim/Vim.git
synced 2024-10-05 16:17:18 +03:00
Some small improvements to CONTRIBUTING.md
and STYLE.md
This commit is contained in:
parent
c842439c5d
commit
135e437528
99
.github/CONTRIBUTING.md
vendored
99
.github/CONTRIBUTING.md
vendored
@ -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:<YOUR-FORK>/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:<YOUR-FORK>/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 <REGEX> # Run only tests/suites matching <REGEX> 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-<MAJOR>.<MINOR>.<PATCH>.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-<MAJOR>.<MINOR>.<PATCH>.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).
|
||||
|
29
STYLE.md
29
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.
|
||||
|
Loading…
Reference in New Issue
Block a user