diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 44c3c7d..daa4f56 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,8 +6,8 @@ Keep in mind that these are guidelines, not rules. Use your best judgement and f Please use the follow general workflow when making contributions to the code: 1. Fork the repository. -2. Create a feature branch or commit directly to the `develop` branch. -3. Create a pull request to request that your commits be merged to the `develop` branch of the `vscode-xml` repository. PRs submitted to the `master` branch will not be considered. +2. Create a feature branch and make your changes. +3. Create a pull request to request that your commits be merged to `master`. ## Building the Extension @@ -15,35 +15,29 @@ Please use the follow general workflow when making contributions to the code: 2. Run the `build` task in VS Code (`CTRL + SHIFT + B`) or start extension debugging (`F5`), which will run the `build` task for you. ## Style Guide +### Quotes +Use double quotes for strings whenever possible. + ### Imports -To keep *.ts files from getting too cluttered, use a namespace alias when pulling in more than 4 or 5 objects. As a general rule, always import the `vscode` namespace using the `vsc` alias for consistency. - -**Favor This** - -`import * as abc from 'abclib';` - -**Over This** - -`import { SomeType, AnotherType, BigClassWithCrazyName, IwantThisToo, VeryAppealingClass, Gimmee } from 'abclib';` +As a general rule, always import the `vscode` namespace using the `vsc` alias for consistency. ### Static Classes When possible, try to use a static class to wrap utility functions so you are importing the class, not just a function. -For libraries that do not follow this construct (such as the `xpath` module), *always* import the module using an alias (`import * as xpath from 'xpath'). +For libraries that do not follow this construct (such as the `xpath` module), *always* import the module using an alias (`import * as xpath from "xpath"). ### Constants Where applicable, try to use constants instead of inline strings and numbers. ## Implicit Types -Moving forward, the compiler is instructed (via tsconfig.json) to throw warnings if any expressions imply an "any" type. In other words, always use type declarations where applicable so it is clear what type is being used. +Moving forward, the compiler is instructed (via tsconfig.json) to throw warnings if any expressions imply an `any` type. In other words, always use type declarations where applicable so it is clear what type is being used. There is an exception to this guideline. If you are using a thrid party library that does not have a *.d.ts file available, you do not need to write one. Just ensure the API is documented (either in this repo or in the library's repo). - ## Folder Structure All TypeScript files should reside under the top `src` folder. Under this, there are several subfolders and top-level files defined below: ### providers This folder contains any classes that implement provider interfaces from the `vscode` namespace. This folder also contains any code that works directly with the -APIs exposed by the `vscode` namespace, such as user interaction or configuration access. Aside for the `vscode` module, no code in this folder should be dependent on +APIs exposed by the `vscode` namespace, such as user interaction or configuration access. Aside for the `vscode` module, no code in this folder should be directly dependent on any external NodeJS modules or libraries. ### services @@ -51,12 +45,10 @@ This folder contains any classes that perform actions/logic required by the prov dependent on external Node modules and libraries. ### utils -This folder contains any utility classes/functions that might be used by providers. +This folder contains any utility classes/functions. ### Commands.ts This file acts as an interface to all registered commands in the extension. If a substantial amount of code is required to implement a command, it should be moved to a provider and/or service. -Otherwise, if a command can be implemented in just a few lines, that code can be placed here. ### Extension.ts -Previously named `main.ts`, this is the primary entry point to the extension. Anything that needs done on activation or deactivation of the extension is done here. Both the workspace -and global `Memento` instances are exposed from this module, which can be used by providers as needed. +Previously named `main.ts`, this is the primary entry point to the extension. Anything that needs done on activation or deactivation of the extension is done here. Both the workspace and global `Memento` instances are exposed from this module, which can be used by providers as needed.