From a99422895ae8cce7641a3000dd194c00bb4901e5 Mon Sep 17 00:00:00 2001 From: Raul Jimenez Ortega Date: Fri, 22 Sep 2023 16:10:31 +0200 Subject: [PATCH 1/2] Adding 'How I can contribute', and refactoring content --- CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++------------------ 1 file changed, 39 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b6084a9..1615028 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,45 +6,53 @@ Esri welcomes contributions from anyone and everyone. Please see our [guidelines **Table of Contents** -- [How to add new snippets using VS Code **User Snippets**](#how-to-add-new-snippets-using-vs-code-user-snippets) +- [I want to contribute, what should I work on?](#i-want-to-contribute-what-should-i-work-on) +- [Getting a development environment set up](#getting-a-development-environment-set-up) +- [Adding a new snippet](#adding-a-new-snippet) - [arcgis-jsapi-snippets conventions](#arcgis-jsapi-snippets-conventions) - [`prefix` conventions](#prefix-conventions) - [`name` conventions](#name-conventions) - [`description` conventions](#description-conventions) - [`body` conventions](#body-conventions) +- [Pull request](#pull-request) - [Additional resources](#additional-resources) -## How to add new snippets using VS Code **User Snippets** +## I want to contribute, what should I work on? -Steps: +You can help mostly by: + +* Adding ideas for snippets using the [snippet builder](https://esri.github.io/arcgis-js-vscode-snippets/builder/). +* Requesting updates for existing snippets by creating a [Enhancement issue](https://github.com/Esri/arcgis-js-vscode-snippets/issues/new?assignees=&labels=type%2Fenhancement%2C0+-+new%2Cneeds+triage&projects=&template=enhancement.yml). +* Reporting problems by creating a [Bug issue](https://github.com/Esri/arcgis-js-vscode-snippets/issues/new?assignees=&labels=type%2Fenhancement%2C0+-+new%2Cneeds+triage&projects=&template=bug.yml). +* Working on the issues marked as `help wanted`. There is also a `good first issue` label if you are just getting started. + * Comment on the issue and check if any additional context is needed before you start working. This will also help everyone knows that you are already working on it. +* Sharing your own list to the [community snippets](https://github.com/Esri/arcgis-js-vscode-snippets#community-snippets) + +## Getting a development environment set up + +> **Note**: to avoid conflicts, we do not recommend editing the local installation of the plugin placed in (`~/.vscode/extensions/esri.arcgis-jsapi-snippets-version`) + +**Steps:** 1. In VSCode show command palette pressing: `Cmd + Shift + P` (Windows: `Ctrl + Shift + P`) then type/select `Preferences: Configure User Snippets`. 2. Select your preferred option, `New Global Snippets file...` or the folder you want to place the snippets file. 3. Depending on the type of snippet you want to add, you need to type: `html.json`, `javascript.json`, `json.json`, `typescript.json` or `typescriptreact.json.` -4. Now you can test it there. You will need to use the command palette again but instead, type `Developer: Reload Window` for VS Code to recognize the new snippet. Use the additional resources if needed. -5. Whenever you are ready to add it: - 5.1. Add a fork of [this repo](https://github.com/Esri/arcgis-js-vscode-snippets). - 5.1. Update the file in the [snippets](./snippets) (respects the alphabetical order). - 5.2. Update the [CHANGELOG.md](./CHANGELOG.md) file to reflect the changes. - 5.3. Add the info to the [snippets table](./README.md) - 5.4. Submit your PR - -> **Note**: to avoid conflicts, we do not recommend to edit the local installation of the plugin placed in (`~/.vscode/extensions/esri.arcgis-jsapi-snippets-version`) - -## arcgis-jsapi-snippets conventions +4. Now you can test it there. You will need to use the command palette again but instead, type `Developer: Reload Window` for VSCode to recognize the new snippet. -If you want to contribute to this extension, please read and follow this convetions before doing a pull request. +## Adding a new snippet We accept different type of snippets: * Initialization of classes. (E.g. `new FeatureLayer({ ... })`). -* JS objects with contructor properties (`{ url: ... }`). +* JS objects with constructor properties (`{ url: ... }`). * Common procedures (E.g. query a layer, disable navigation, project a geometry, ...). * Enumeration of possible values (E.g: basemap styles, renderer and symbol types, ...). -> **Note**: You can use the the issue on each section to ask or discuss anything related to these conventions. +Consider using the [snippet builder](https://esri.github.io/arcgis-js-vscode-snippets/builder/) to validate your snippet, and please make sure it follows the [conventions](#conventions). + +## arcgis-jsapi-snippets conventions ### `prefix` conventions @@ -188,10 +196,19 @@ For methods like [fromJSON()](https://developers.arcgis.com/javascript/latest/ap ${1|Simple,UniqueValue,ClassBreaks,Dictionary,DotDensity,Heatmap|}Renderer.fromJSON(json) ``` +## Pull request + +Before each PR follow these steps: + +1. Update the file in the [snippets folder](./snippets) (respects the alphabetical order). +2. Update the [CHANGELOG.md](./CHANGELOG.md) file to reflect the changes. +3. Add the info to the [snippets table](./README.md). +4. Submit your PR. + ## Additional resources -- [VS Code Snippet Generator](https://snippet-generator.app/) -- [Snippets in Visual Studio Code](https://code.visualstudio.com/docs/editor/userdefinedsnippets) -- [Your First Extension | Visual Studio Code Extension API](https://code.visualstudio.com/api/get-started/your-first-extension) -- [JS IntelliSense in VSCode](https://code.visualstudio.com/docs/languages/javascript#_intellisense) -- [IntelliSense in VSCode](https://code.visualstudio.com/docs/languages/javascript#_intellisense) \ No newline at end of file +- [Visual Studio Code Snippets Builder](https://esri.github.io/arcgis-js-vscode-snippets/builder). +- Visual Studio Code official documentation: + - [Editor > Languages > JavaScript > IntelliSense](https://code.visualstudio.com/docs/languages/javascript#_intellisense). + - [Editor > User guide > Snippets > Snippets syntax](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_snippet-syntax). + - [API > Get started > Your First Extension](https://code.visualstudio.com/api/get-started/your-first-extension). \ No newline at end of file From 9403ba4817eb8fefceb27ef635f0f339353e828d Mon Sep 17 00:00:00 2001 From: Raul Jimenez Ortega Date: Fri, 22 Sep 2023 16:22:40 +0200 Subject: [PATCH 2/2] Adding name and snippets conventions - closes #10, closes #20 --- CONTRIBUTING.md | 77 +++++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1615028..72ef856 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,11 +9,11 @@ Esri welcomes contributions from anyone and everyone. Please see our [guidelines - [I want to contribute, what should I work on?](#i-want-to-contribute-what-should-i-work-on) - [Getting a development environment set up](#getting-a-development-environment-set-up) - [Adding a new snippet](#adding-a-new-snippet) -- [arcgis-jsapi-snippets conventions](#arcgis-jsapi-snippets-conventions) - - [`prefix` conventions](#prefix-conventions) - - [`name` conventions](#name-conventions) - - [`description` conventions](#description-conventions) - - [`body` conventions](#body-conventions) +- [Conventions](#conventions) + - [`prefix`](#prefix) + - [`name`](#name) + - [`description`](#description) + - [`body`](#body) - [Pull request](#pull-request) - [Additional resources](#additional-resources) @@ -52,44 +52,40 @@ We accept different type of snippets: Consider using the [snippet builder](https://esri.github.io/arcgis-js-vscode-snippets/builder/) to validate your snippet, and please make sure it follows the [conventions](#conventions). -## arcgis-jsapi-snippets conventions +## Conventions -### `prefix` conventions +### `prefix` -> These [conventions were discussed on issue #10](https://github.com/Esri/arcgis-js-vscode-snippets/issues/10). +* Avoid acronyms (like `sms` for `SimpleMarkerSymbol`) +* Use camelcase (not [snake_case](https://en.wikipedia.org/wiki/Snake_case), UPPERCASE, etc.) +* Per snippet type: + * **Class properties objects**: add the suffix "Props". + * **Class constructors**: match JS SDK capitalization. -* Try not to use just acronyms (like `sms` for `SimpleMarkerSymbol`) -* If the snippet only contain and object with properties to initialize a class add the suffix "Props". +> If you want to suggest a change, please [check the issue #10](https://github.com/Esri/arcgis-js-vscode-snippets/issues/10). -### `name` conventions +### `name` -> These [conventions were discussed on issue #20](https://github.com/Esri/arcgis-js-vscode-snippets/issues/20). +* Start your sentence with capitals (do not capitalize, uppercase) +* Use spaces as needed (don't put words together or use [camelCase](https://en.wikipedia.org/wiki/Camel_case), [snake_case][https://en.wikipedia.org/wiki/Snake_case], etc.). +* Keep the name short as possible (<35 characters max) to avoid ellipsis ("..."). -*To be decided* +> If you want to suggest a change, please [check the issue #20](https://github.com/Esri/arcgis-js-vscode-snippets/issues/20). -### `description` conventions - -> These [conventions were discussed on issue #21](https://github.com/Esri/arcgis-js-vscode-snippets/issues/21). +### `description` * It should be a proper description of what the snippet does, and reuse text from the API reference whenever possible. * If it is a snippet related to a class/module include the AMD and ESM paths. For example: `Convert a geometry from Web Mercator units (wkid: 3857) to geographic units (wkid: 4326). AMD path: esri/geometry/support/webMercatorUtils | ESM path: @arcgis/core/geometry/support/webMercatorUtils.js` -### `body` conventions +> If you want to suggest a change, please [check the issue #21](https://github.com/Esri/arcgis-js-vscode-snippets/issues/21). + +### `body` -> These [conventions were discussed on issue #19](https://github.com/Esri/arcgis-js-vscode-snippets/issues/19). +> If you want to suggest a change, please [check the issue #19](https://github.com/Esri/arcgis-js-vscode-snippets/issues/19). -* Use \t instead of spaces. [Example 1](#body-example-1) -* Don't add comments in your snippets. [Example 2](#body-example-2) -* Try to keep snippets small, and try not to instantiate more than one class whenever possible. [Example 3](#body-example-3) -* Conventions about constructor objects: [Example 4](#body-example-4) - * Sort properties by alphabetical order. - * Try to include only the most common properties. - * If a property expects another instance of class, add the name of the snippet (if it exists). - * When a property support multiple value types, add just a placeholder. -* After a class initialization, don't assign it to a variable. [Example 5](body-example-5) -* For inherited methods, try make generic snippets. [Example 6](body-example-6) +#### 1) Use `\t` for tabs (do not use spaces) -#### `body` example 1 +**Example:** ```js { @@ -109,7 +105,9 @@ Consider using the [snippet builder](https://esri.github.io/arcgis-js-vscode-sni } ``` -#### `body` example 2 +#### 2) Don't add comments in your snippets + +**Example:** ```js // queries all features in the layer @@ -118,9 +116,11 @@ myLayer.queryFeatures().then(results => { }) ``` -#### `body` example 3 +#### 3) Keep snippets small -Keeping snippets small helps make them more reusable. So insted of doing this: +Try not to instantiate more than one class whenever possible. Keeping snippets small helps make them more reusable. So instead of doing this: + +**Example:** ```js const webmap = new WebMap({ @@ -152,7 +152,14 @@ new MapView({ }); ``` -#### `body` example 4 +#### 4) Conventions for constructor properties + +* Sort properties by alphabetical order. +* Include what you think are the most common properties. +* If a property expects another instance of class, add the name of the snippet (if it exists). +* When a property support multiple value types, add just a placeholder. + +**Example:** ```js new PopupTemplate({ @@ -166,7 +173,7 @@ new PopupTemplate({ Observe the [PopupTemplate property "content"](https://developers.arcgis.com/javascript/latest/api-reference/esri-PopupTemplate.html#content) include a list of possible values, and `popupContent` will trigger other snippets like: `popupCustomContent`, `popupMediaContent`, `popupFieldsContent`, `popupTextContent` and `popupAttachmentsContent`. -#### `body` example 5 +#### 5) After a class initialization, don't assign it to a variable Avoid doing this: @@ -188,7 +195,7 @@ new WebMap({ }) ``` -#### `body` example 6 +#### 6) For inherited methods, try to make generic snippets. For methods like [fromJSON()](https://developers.arcgis.com/javascript/latest/api-reference/esri-renderers-Renderer.html#methods-summary), which is inherited in many classes, for example: SimpleRenderer, UniqueValueRenderer, HeatmapRenderer, ... do something like this: