Skip to content

Commit

Permalink
docs(contributing, conventions): proofread and add additional info (#…
Browse files Browse the repository at this point in the history 
…5228)

**Related Issue:** #3818

## Summary
- Added additional information to the contributing and documentation convention.
- Fixed outdated info
<!--

Please make sure the PR title and/or commit message adheres to the https://www.conventionalcommits.org/en/v1.0.0/ specification.

Note: If your PR only has one commit and it is NOT semantic, you will need to either

a. add another commit and wait for the check to update
b. proceed to squash merge, but make sure the commit message is the same as the title.

This is because of the way GitHub handles single-commit squash merges (see zeke/semantic-pull-requests#17)

If this is component-related, please verify that:

- [ ] feature or fix has a corresponding test
- [ ] changes have been tested with demo page in Edge

---

If this is skipping an unstable test:

- include info about the test failure
- submit an unstable-test issue by [choosing](https://github.com/Esri/calcite-components/issues/new/choose) the unstable test template and filling it out

-->
  • Loading branch information
@benelan
benelan authored Sep 2, 2022
1 parent 40a3f11 commit 2898851
Show file tree
Hide file tree
Showing 2 changed files with 94 additions and 41 deletions.
72 changes: 39 additions & 33 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,12 @@ Note: New contributors should first contact [Ben Elan](mailto:[email protected]) or

Calcite Components is still in its early stages. You can help most by:

- Adding ideas for components to our [wishlist project](https://github.com/Esri/calcite-components/projects/2). We are using the wishlist to gather ideas about useful components which we may be able to add to Calcite Components.
- Working on [the issues](https://github.com/Esri/calcite-components/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+no%3Aassignee) marked as `help wanted`. There is also a `good first issue` label if you are just getting started.
- If you want to help develop components take a look at [1.0.0 components](https://github.com/Esri/calcite-components/projects/1) which are the components we are targeting for the first release of Calcite Components. Before starting development please review our [component conventions](./conventions/README.md) and the [Stencil documentation](https://stenciljs.com/docs/host-element).
- Adding ideas for components by [creating a New Component issue](https://github.com/Esri/calcite-components/issues/new?assignees=&labels=new+component%2C0+-+new%2Cneeds+triage&template=new-component.yml).
- Requesting features for existing components by [creating a Enhancement issue](https://github.com/Esri/calcite-components/issues/new?assignees=&labels=enhancement%2C0+-+new%2Cneeds+triage&template=enhancement.yml).
- Reporting problems by [creating a Bug issue](https://github.com/Esri/calcite-components/issues/new?assignees=&labels=bug%2C0+-+new%2Cneeds+triage&template=bug.yml).
- Working on [the issues marked as `help wanted`](https://github.com/Esri/calcite-components/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+no%3Aassignee). There is also a `good first issue` label if you are just getting started.
- Comment on the issue and ask for the action items before you start working. Sometimes additional context is needed, which may not be specified in the issue.
- If you want to help develop components take a look at the [new component issues](https://github.com/Esri/calcite-components/issues?q=is%3Aopen+is%3Aissue+label%3A%22new+component%22). Before starting development please review our [component conventions](./conventions/README.md) and the [Stencil documentation](https://stenciljs.com/docs/introduction).

If you aren't familiar with the basics of Web Components and Shadow DOM, please read through some of the following resources before contributing:

Expand All @@ -31,6 +34,10 @@ If something isn't working the way you expect, please take a look at the [existi

## Issue management

### Labels

GitHub labels are used for organizing issues and providing context. You can familiarize yourself with the [label descriptions](https://github.com/Esri/calcite-components/labels) to understand what they signify.

### Lifecycle

There are four issue lifecycle labels:
Expand All @@ -43,9 +50,17 @@ There are four issue lifecycle labels:

An issue can only have one of the lifecycle labels at any time. Please make sure to keep these up to date.

### Issues that cannot be worked on

There are three labels that mean an issue is not ready for development:

- `design`: Issues that need design consultation, such as interaction research/feedback, visual mockups, and general approval. Once design completes their review, the `design` label will be removed, which means a developer can pick up the issue.
- `need more info`: Issues that are missing information and/or a clear, actionable description. This can mean we are waiting on a user to provide additional context, we can't reproduce the issue, or further discussion is needed in order to determine a solution.
- `blocked`: Issues that cannot be worked on until a different issue is resolved. The blocking issue may be from an external library (Stencil, Storybook, Jest, etc.) or a Calcite Components issue. The blocking issue should be linked to in the blocked issue's body or comment.

### Milestones

Milestones are used to manage sprints, which are two weeks long. Sprint milestones are not closed until all of the issues are verified. We usually have a couple sprint milestones open at a time to help with future planning. Grab issues from the current sprint when you are looking for something to work on. There are also two constant milestones:
Milestones are used to manage sprints, which are two weeks long. Sprint milestones are not closed until all of the issues are verified. We usually have a couple sprint milestones open at a time to help with future planning. Calcite Core team members should grab issues from the current sprint when you are looking for something to work on. External contributors should ask before working on issues in upcoming sprints, since some of them need to be completed in a timely manner. There are also two constant milestones:

- **Backburner:** Issues we want to tackle soon, but not in the immediate sprint. If you didn't find anything to work on in the current sprint, this is the second place to look.
- **Freezer:** Items that we want to look into, but do not have an immediate timeline associated. Try not to work on these issues unless they have a `help wanted` label.
Expand All @@ -59,6 +74,10 @@ Milestones are used to manage sprints, which are two weeks long. Sprint mileston
- **13:** Issues that are more complicated and need some workflow or design planning. These issues usually need additional unit tests written.
- **40:** If an issue is this complicated it should be converted into an epic.

### Epics

Epics are specified by the `epic` label. Epics are changes that require a lot of work and wouldn't fit into a single milestone. An epic should be a single concept, and have child issues for individual tasks created and listed in the epic's issue body.

## Code base

Our code base is written in TypeScript and must adhere to specific conventions and formatting. Please do the following while developing:
Expand All @@ -70,16 +89,14 @@ Our code base is written in TypeScript and must adhere to specific conventions a

## Getting a development environment set up

We recommend installing the following extensions in your editor of choice: TypeScript, Sass, TailwindCSS, ESLint and Prettier.
An installation of Node is required for development. If you don't have Node installed, we recommend [Volta], which will automatically use the Node versions we pinned in `package.json`. We also recommend installing the following extensions in your editor of choice: TypeScript, TailwindCSS, ESLint, Stylelint, and Prettier. If you use VS Code, you will see a pop up in the bottom right corner prompting you to install or view the workspaces's recommended extensions. Here are instructions for manually installing the extensions in a variety of editors:

- https://code.visualstudio.com/
- https://atom.io/packages/atom-typescript
- https://github.com/Microsoft/TypeScript-Sublime-Plugin
- https://tailwindcss.com/docs/intellisense
- https://github.com/neoclide/coc.nvim
- etc...
- https://eslint.org/docs/latest/user-guide/integrations
- https://stylelint.io/user-guide/integrations/editor
- https://prettier.io/docs/en/editors.html

To start the local development environment run `npm start` this will start the local Stencil development server on http://localhost:3333. You can modify the [index.html](./src/index.html) to add and test your new component. Just add another HTML file to the `demos` folder and link to this new page from `index.html`.
To start the local development environment, run `npm start`, which will start the local Stencil development server on localhost. You can modify the [index.html](./src/index.html) to add and test your new component. Just add another HTML file to the `demos` folder and link to this new page from `index.html`.

## Linting

Expand All @@ -93,36 +110,23 @@ Calcite Components include Stencil's default testing tools which are built on [J

If you're working on writing tests for a particular component, it can be helpful to use `npm run test:watch` to retest on file changes. Once the initial tests run, typing `o` at the prompt will run tests only on changed files, allowing you to quickly iterate on tests for a specific component.

Please refer to the [Stencil testing documentation](https://stenciljs.com/docs/testing-overview) for more information.
Please refer to the [Stencil testing documentation](https://stenciljs.com/docs/testing-overview) and Calcite's [testing conventions](./conventions/Testing.md) for more information.

## Adding a new component

Before adding a new component, please read through the [component conventions guide](./conventions/README.md). This guide covers everything from colors to event naming syntax and will help you create a component that is consistent with those that exist already. All new components should have an [issue](https://github.com/Esri/calcite-components/issues/new?assignees=&labels=new+component%2C+0+-+new%2C+architecture&template=new-component.md&title=New+Component%3A+).
Before adding a new component, please read through the [component conventions guide](./conventions/README.md). This guide covers everything from colors to event naming syntax and will help you create a component that is consistent with those that already exist. All new components should have an [issue](https://github.com/Esri/calcite-components/issues/new?assignees=&labels=new+component%2C+0+-+new%2C+architecture&template=new-component.md&title=New+Component%3A+).

## Documenting a component

Calcite Components utilizes [Storybook](https://storybook.js.org/) for documenting components. Adding a new component is very simple:
Stencil creates API reference documentation using JSDoc, here is their [documentation page](https://stenciljs.com/docs/docs-json). Calcite Components utilizes [Storybook](https://storybook.js.org/) for documenting components. Adding a new component is very simple:

1. Create a new file inside your component directory like `X.stories.js`
2. Write stories (see below)
2. Write stories
3. Run the documentation locally with `npm run docs:preview`

The `docs:preview` command will build Calcite Components and open your browser to view the storybook docs locally.

### Writing stories

Each component should use a `storiesOf` with at least one story. It's a great idea to add the component's auto-generated `readme.md` as notes. If your component has props that effect visual styles, you can use the [storybook knobs addon](https://www.npmjs.com/package/@storybook/addon-knobs) to allow people to manipulate props and see live updates in the documentation. A minimal stories file might look something like this:

```
import { storiesOf } from '@storybook/html';
import { boolean } from '@storybook/addon-knobs'
import notes from './readme.md';
storiesOf('My component', module)
.add('Simple', () => `
<my-component demo-prop="${boolean("demo-prop", true)}"></my-component>
, { notes })`
```
Please refer to the [Documentation Conventions](./conventions/Documentation.md) for more information.

## Branch naming conventions

Expand Down Expand Up @@ -154,11 +158,11 @@ johndoe/feature/add-something-to-modal

This project follows [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/), which are used to generate the changelog. Be sure to provide clear and sufficient information in commit messages. This is important because the commit messages are used to automatically update the changelog.

[Stencil's contributing document](https://github.com/ionic-team/stencil/blob/master/.github/CONTRIBUTING.md#commit-message-format) explains this in great detail, so please refer to this for more details and examples.'
[Stencil's contributing document](https://github.com/ionic-team/stencil/blob/master/.github/CONTRIBUTING.md#commit-message-format) explains this in great detail, so please refer to this for more details and examples.

## Breaking Changes
## Breaking changes

For ease of discoverability, commit messages for breaking changes should use both the header (`!`) and body (`BREAKING CHANGE:`) syntax:
Commit messages for breaking changes should use both the header (`!`) and body (`BREAKING CHANGE:`) syntax:

```
<type>!: <descriptive summary>
Expand All @@ -172,4 +176,6 @@ See the [conventional commits doc](https://www.conventionalcommits.org/en/v1.0.0

## Pull requests

In order to ensure conventional commits are followed, pull requests will run a check to indicate whether the PR is following the convention or not. The [Semantic Pull Request](https://github.com/probot/semantic-pull-requests) status check will ensure your pull requests are semantic before you merge them.
In order to ensure conventional commits are followed, pull requests will run a check to indicate whether the PR is following the convention or not. The [Semantic Pull Request](https://github.com/amannn/action-semantic-pull-request) status check will ensure your pull requests are semantic before you merge them.

You can update the PR title any time before merging the PR. This may be necessary when the scope or type of the PR changes, or if additional details are needed for the changelog entry.
63 changes: 55 additions & 8 deletions conventions/Documentation.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,67 @@
# Documentation

## Stencil API reference

Stencil uses [JSDoc](https://jsdoc.app) for their API reference generation. Stencil generates a [`docs-json`](https://stenciljs.com/docs/docs-json) output target, which is parsed and displayed on the [SDK site](https://developers.arcgis.com/calcite-design-system/components). The API reference includes property/attribute names, descriptions, types, values, and description notes (e.g. required, optional, deprecated). The SDK site updates the API reference after Calcite Component releases.

### Style guide

Follow these conventions when adding or editing API reference:

- Use complete sentences with proper grammar, capitalization, and punctuation.
- No abbreviations, e.g. use "property" instead of "prop".
- Verbs must be in present tense.
- Use the full tag name when referencing other Calcite Components (prefix with `calcite-`), e.g. `calcite-button` instead of `button`.
- For plural context, use `calcite-button`s instead of `calcite-button` elements.
- Use backticks (`` ` ``) for the names of slots, events, properties, CSS variables, and component names (e.g. `calcite-button` instead of calcite-button).
- Use double quotes (`"`) for the values of properties/attributes and event details.
- Only use single quotes (`'`) as apostrophes.
- No links or URLs allowed in descriptions. If a link is necessary, a [custom JSDoc tag](https://stenciljs.com/docs/docs-json#custom-jsdocs-tags) should be added and parsed in the SDK site.
- Refrain from using "e.g." or "i.e." references. Leverage "such as" (or similar) where examples are referenced.
- Use "Accessible" instead of "Aria" or "a11y" language.
- Verify slots and properties/attributes don't use the text "optional" in their descriptions.

### Deprecation notices

There are two ways to document deprecations, depending on the API reference. In both cases a deprecated chip will be displayed in the SDK site within the component's API reference section.

1. The `@deprecated` JSDoc tag is used for JavaScript properties, events, and methods in the `<component-name>.tsx` file. Notes can accompany the JSDoc tag, such as "use `<property>` instead".
2. The `[Deprecated]` text is added at the beginning of the JSDoc description for slots (`@slots`) in the `<component-name>.tsx` file and CSS variables in the `<component-name>.scss` file. The text is parsed and removed from the description in the SDK site.

### Usage snippets

You can provide code snippets demonstrating a specific behavior or pattern for a component. Within the component's directory, create a new `usage` directory. Then, create a Markdown file with the filename as the title of the snippet. There should only be one snippet per Markdown file. Stencil will add the usage snippets to the component's README after building. These usage snippets will then be displayed in Storybook.

## Storybook

Calcite Components uses [Storybook](https://storybook.js.org/) to provide an interactive showcase of components with accompanying documentation.

For each main component (i.e., one that can be used by itself), there should be a `<component-name>.stories.ts` file in its component folder.
For each main component (i.e. one that can be used by itself), there should be a `<component-name>.stories.ts` file in its component folder.

Each story should provide access to relevant [knobs](https://github.com/storybookjs/storybook/tree/next/addons/knobs) so users can test out different properties.

For additional documentation, create a [usage folder](https://github.com/Esri/calcite-components/tree/master/src/components/action/usage) in the component directory with a basic.md and optionally an advanced.md file (if additional documentation or examples are required) with snippets showing different supported use cases for the component.
### Writing stories

Each component should use the [Component Story Format (CSF)](https://storybook.js.org/docs/html/api/csf) with at least one story. If your component has properties that effect visual styles, you can use the [storybook knobs addon](https://www.npmjs.com/package/@storybook/addon-knobs) to allow people to manipulate properties and see live updates in the documentation. A minimal stories file might look something like this:

```
import { storiesOf } from '@storybook/html';
import { boolean } from '@storybook/addon-knobs'
import notes from './readme.md';
## Code Documentation
export default {
title: "Components/X",
parameters: { notes }
};
[JSDoc](https://jsdoc.app) is used to document each component. After a release, the documentation builds on the respective component page on the [SDK site](https://developers.arcgis.com/calcite-design-system/components) specifying property/attribute names, descriptions, types, values, and description notes (e.g., required, optional, deprecated, etc.).
storiesOf('My component', module)
.add('Simple', () => `
<my-component demo-prop="${boolean("demo-prop", true)}"></my-component>
, { notes })`
```

### Deprecated
Make sure to import the README generated by Stencil so that it can be viewed in Storybook. Storybook is deployed during every `next` version, whereas as the SDK site is only updated after `beta` releases. Storybook is a great resource for testing the newest changes and viewing the newest API reference.

There are two documentation sources for displaying deprecations, depending on the API reference. In both cases a deprecated chip will be displayed within the component's API reference section.
### Using utilities

1. The JSDoc `@deprecated` tag is used for JavaScript properties, events, and methods in the `<component-name>.tsx` file. Notes can accompany the JSDoc tag, such as "use `<property>` instead".
2. The `[Deprecated]` text is used for slots (`@slots`) in the `<component-name>.tsx` file and CSS custom properties in the `<component-name>.scss` file.
There are a variety of Storybook [helpers](../.storybook/helpers.ts) and [utilities](../.storybook/utils.tsx) that should be used for common patterns. You can use existing stories as a reference for when/how the utilities and helpers should be used.

0 comments on commit 2898851

Please sign in to comment.