Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updating CONTRIBUTING.md #29

Merged
merged 2 commits into from
Sep 22, 2023
Merged

Updating CONTRIBUTING.md #29

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a994228
Adding 'How I can contribute', and refactoring content
hhkaos Sep 22, 2023
9403ba4
Adding name and snippets conventions - closes #10, closes #20
hhkaos Sep 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 79 additions & 55 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,82 +6,86 @@ Esri welcomes contributions from anyone and everyone. Please see our [guidelines
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [How to add new snippets using VS Code **User Snippets**](#how-to-add-new-snippets-using-vs-code-user-snippets)
- [arcgis-jsapi-snippets conventions](#arcgis-jsapi-snippets-conventions)
- [`prefix` conventions](#prefix-conventions)
- [`name` conventions](#name-conventions)
- [`description` conventions](#description-conventions)
- [`body` conventions](#body-conventions)
- [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)
- [Conventions](#conventions)
- [`prefix`](#prefix)
- [`name`](#name)
- [`description`](#description)
- [`body`](#body)
- [Pull request](#pull-request)
- [Additional resources](#additional-resources)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## 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
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.

> **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

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).

### `prefix` conventions
## Conventions

> These [conventions were discussed on issue #10](https://github.com/Esri/arcgis-js-vscode-snippets/issues/10).
### `prefix`

* 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".
* 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.

### `name` conventions
> If you want to suggest a change, please [check the issue #10](https://github.com/Esri/arcgis-js-vscode-snippets/issues/10).

> These [conventions were discussed on issue #20](https://github.com/Esri/arcgis-js-vscode-snippets/issues/20).
### `name`

*To be decided*
* 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 ("...").

### `description` conventions
> If you want to suggest a change, please [check the issue #20](https://github.com/Esri/arcgis-js-vscode-snippets/issues/20).

> 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
{
Expand All @@ -101,7 +105,9 @@ We accept different type of snippets:
}
```

#### `body` example 2
#### 2) Don't add comments in your snippets

**Example:**

```js
// queries all features in the layer
Expand All @@ -110,9 +116,11 @@ myLayer.queryFeatures().then(results => {
})
```

#### `body` example 3
#### 3) Keep snippets small

Try not to instantiate more than one class whenever possible. Keeping snippets small helps make them more reusable. So instead of doing this:

Keeping snippets small helps make them more reusable. So insted of doing this:
**Example:**

```js
const webmap = new WebMap({
Expand Down Expand Up @@ -144,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({
Expand All @@ -158,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:

Expand All @@ -180,18 +195,27 @@ 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:

```js
${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)
- [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).