CONTRIBUTING.md

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Note: New contributors should first contact Ben Elan or Juan Carlos Franco to join the Calcite Contributors GitHub team. Then, clone the repo via SSH key on your machine (this Git workflow is required in order to work with our Chromatic test integration).

I want to contribute, what should I work on?

You can help most by:

• Reporting issues by filing a Bug issue.
• Requesting features for existing components by creating an Enhancement issue.
• Adding ideas for components by creating a New Component issue.
• Working on the issues marked as help wanted. There is also a good first issue label if you are just getting started.
  • To let us know of your interest in the issue, please 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. Comments also provide us access to assign the issue to you.
• If you want to help develop components take a look at the new component issues. Before starting development please review our component conventions and the Stencil documentation.

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

• Google - Custom Elements v1: Reusable Web Components
• Google - Shadow DOM v1: Self-Contained Web Components
• CSS Tricks - An Introduction to Web Components

Before filing an issue

Have you found a new bug? Want to request a new feature? We'd love to hear from you!

If something isn't working the way you expect, take a look at the existing issues before logging a new one. You can also report a bug or request an enhancement with Esri Support, or ask questions, share ideas, and collaborate with others on Esri Community.

When filing an issue, provide all of the requested info from the appropriate issue template so we can work on resolving the issue as soon as possible. A sample that reproduces the issue is required for logging bugs - we created templates in codepen, codesandbox, and jsbin (with the ArcGIS Maps SDK for JavaScript) to get you started. Alternatively, a documentation sample can be used if the issue is reproducible. Some other considerations:

• Use a clear and descriptive title
• Describe what is happening now vs what should happen
• Tell us how to reproduce the issue (e.g., is it happening in a specific browser?)
• Can it be reliably reproduced? If not, tell us how often it happens and under what circumstances.
• Screenshots and GIFs are welcome!
• Did this problem start happening after a recent release, or was it always a bug?

Issue management

Labels

GitHub labels are used for organizing issues and providing context. You can familiarize yourself with the label descriptions to understand what they signify.

Lifecycle

There are four issue lifecycle labels:

• 0 - new: Issues that are up for grabs.
• 1 - assigned: Issues that someone will work on soon.
• 2 - in development: Issues are currently being worked on.
• 3 - installed: Issues that have been merged to main.
• 4 - verified: Issues that have been tested and are ready to close.

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 four 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, an additional label, ready for dev will be added to the issue, which means a developer can pick up the issue.
• spike: Issues that need to research a question or resolve a complex task with uncertain outcomes. Once the spike has been performed a spike complete label is added to the issue, 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. In the body or comments of a blocked issue, include a link to the blocking issue. To track when an issue is unblocked, add a comment in the blocking issue's body referencing the blocked issue(s). Use the following format for the comment: "Blocked issues: #0000, #0000". List multiple blocked issues by separating them with commas.

Milestones

Milestones are used to organize issues targeted for a sprint in a planned release, and are not closed until all of the issues are verified. We have multiple milestones open at a time to help with future sprint planning. Calcite Core team members should grab issues from the current milestone when you are looking for something to work on. External contributors should ask before working on issues in upcoming milestones, since some of them need to be completed in a timely manner. There are also two constant milestones:

• Stalled: Issues we want to work on now, but are blocked, missing information, or require discussion to define action items. Try not to work on these issues unless an issue has a spike label and the research can be added to the issue for consideration in a future sprint.
• 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.

Estimates

Estimates are used to determine how much effort needs to go into an issue. The total estimate helps product managers triage issues effectively so designers and developers are not overwhelmed during sprints. If you are not on the team, please do not add estimates when creating cases. Here are some guidelines for time estimates using an estimate-# label for tracking:

Design estimates

• estimate - design - sm: No more than a few days of design expertise.
• estimate - design - md: One to two weeks of design efforts and collaboration.
• estimate - design - lg: Two to four weeks of design expertise, collaboration, and discussion. Usually requires all hands on deck.

Development estimates

• estimate - 1: Very small fix or change, a one line update.
• estimate - 2: Small fix or update, does not require updates to tests.
• estimate - 3: A day or two of effort, may require changes to tests.
• estimate - 5: A few days of effort, requires updates to tests.
• estimate - 8: Requires input from team, consider smaller steps.
• estimate - 13: Requires planning and input from team, consider smaller steps.
• estimate - 21: Requires planning, input from team members and possibly others.
• estimate - 34: Issue should be converted into an epic. Requires all hands on deck.

Epics

Epics are specified by the epic label. Epics are changes that require a considerable effort 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:

1. Avoid setting types as any.
2. Try to always provide a type.
3. Provide JSDoc for all public APIs.
4. Fix linting errors, don't ignore them.

Getting a development environment set up

An installation of Node is required for development. If you don't have Node installed, we recommend Volta, which will automatically use the Node/NPM versions pinned at the bottom of package.json. If you prefer a different Node version manager, make sure to use the major versions of Node/NPM specified under the "volta" key 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://tailwindcss.com/docs/intellisense
• https://eslint.org/docs/latest/user-guide/integrations
• https://stylelint.io/user-guide/integrations/editor
• https://prettier.io/docs/en/editors.html

If your IDE supports the Language Server Protocol (LSP) specification but isn't mentioned in the links above, ask Ben for help getting set up.

NOTE: If you are on Windows, we strongly recommend using the Bash emulation that ships with Git for Windows. Or better yet, use Ubuntu in WSL! Otherwise, keep in mind that some of the scripts used by maintainers (such as for releasing) likely won't work in Command Prompt or PowerShell. However, please log an issue if scripts used for normal development (start/test/build/etc) don't work in your Windows environment.

Starting the demos

First, clone the repo and then install the NPM dependencies:

git clone git@github.com:Esri/calcite-design-system.git
cd calcite-design-system
npm install

Next, start the local Stencil development server on localhost:

npm run start:components

The demos will open in the browser after building. Edit the pages in packages/calcite-components/src/demos to modify the component demos, such as changing attributes or adding content to slots. When adding a new demo page, make sure to add a link in packages/calcite-components/src/index.html so others can find it. You can also edit the component code in packages/calcite-components/src/components, and the changes will be reflected in the demos.

Linting

This project uses lint-staged to automatically format code on commit, making it easier to contribute. Each package has it's own linting NPM scripts, so check there for more options. For example, calcite-components has NPM scripts that lint by different filetypes. To run the lint NPM script for all packages that have one, do:

npm run lint

Or use the --workspace flag to lint a single package.

npm --workspace=packages/calcite-components run lint

You can avoid using the --workspace flag in every command by cding into the package you're working on:

cd packages/calcite-components
# the following will only lint and test calcite-components
npm run lint
npm test

Running the tests

npm test will run the test suites.

Calcite Components include Stencil's default testing tools which are built on Jest and Puppeteer.

If you're working on writing tests for a particular component, it can be helpful to use npm --workspace=packages/calcite-components 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. You can also add a pattern to the end of the command to match for a test's file path.

Please refer to the Stencil testing documentation and Calcite's testing conventions for more information.

Adding a new component

Before adding a new component, please read through the component conventions guide. 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.

Documenting a component

Stencil creates API reference documentation using JSDoc, here is their documentation page. Calcite Components utilizes Storybook 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
3. Run the documentation locally with npm --workspace=packages/calcite-components run docs:preview

Calcite Component's docs:preview command will build and open your browser to view the storybook docs locally.

Please refer to the Documentation Conventions for more information.

Branch naming conventions

When submitting a pull request, please use one of the following formats for your branch name:

For pull requests associated with an existing issue:

<username>/<issue-id><issue-description>
johndoe/15-update-modal
johndoe/update-modal-15

For pull requests without an associated issue:

<username>/<issue-description>
johndoe/modal-styling

<username>/<type-of-pr><issue-description>
johndoe/docs/update-modal-docs
johndoe/feature/add-something-to-modal

Commit message format

Calcite follows conventional commits, 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 generate the changelog automatically.

Contributions should adhere to the <type>(<scope>): <descriptive summary> format and include the following:

• Convention type
• Scope of change, optional
• Descriptive commit subject

Check out the contribution example for a formatted example, and explore breaking change formatting for consideration during Calcite's breaking change releases.

Convention type

Contributions must adhere to one of the following conventions:

• chore: Adds a new build process, or auxiliary tool and libraries (e.g., documentation generation) 🤖
• docs: Documentation only changes 📚
• feat: Adds a new feature, or functionality ✨
• fix: Fixes a bug 🐛
• perf: A change improving performance 🚀
• refactor: A change that neither fixes a bug or adds a feature 🔁
• revert: Reverts a previous commit ↪️
• test: Improves test coverage in updating a test or adding a new, or missing test 🧪
• deprecate: Documentation only changes for a deprecation 👎

Scope of change

Optional. Most contributions will include a scope, such as a component, multiple components, test(s), or utilities. For example:

• text-area
• dropdown, dropdown-group, dropdown-item
• common

Not all commits will contain a scope, however it is recommended to include scope when possible.

Descriptive commit subject

The subject should contain a concise description of the proposed change, where contributors will:

• Be succinct, yet informative to ensure the change's purpose is conveyed once added to the changelog
• Describe the commit's purpose, not a related issue or how the change was mitigated
• Use present tense, such as "update" instead of "updated" or "updates"
• Not capitalize the first letter
• Not insert a period . at the end

Contribution example

For instance, if providing a bug fix to the Text Area component, which includes additional support to assistive technologies, you could use the following conventional commit:

fix(text-area): provide additional support to assistive technologies

A more in-depth description can be added to the PR's body summary. For example:

Related Issue: <Issue number>

### Summary
Provide additional context for assistive technology users when the component's character limit exceeds the `maxLength` property. Assistive technology users recieve an error message as soon as the character limit is exceeded.

For more information, explore Stencil's contributing document. Please refer to the above link for more conventional commit details and examples, and visit Calcite's recent commits to refer to additional examples.

Breaking changes

Calcite Core team members should be consulted prior to submitting breaking change pull requests. For stability and consistency, breaking change sprints are coordinated and communicated well in advance.

When breaking changes are supported in a current milestone, commit messages for breaking changes should use both the header (!) and body (BREAKING CHANGE:) syntax.

The PR's details should be comprehensive, and when possible, include the following:

• What the proposed breaking change includes
• Why the breaking change is proposed
• An example to support users migrating from the previous major version (e.g., 1.x to 2.x)

For PR examples, refer to previous changelog entries from the 2.0 major releases for calcite-components and calcite-design-tokens. Also explore the breaking change structure below:

<type>(<scope>)!: <descriptive summary>

<optional info>

BREAKING CHANGE: <What the breaking change includes, why it is proposed, and migration support for users>

When adding a BREAKING CHANGE: note to the summary block right before confirming a squash merge, remove all the info except the BREAKING CHANGE: note itself, or else everything ends up being added to the changelog.

Breaking change contribution example

For instance, if adding a refactored breaking change to the Modal component, you could use the following conventional commit:

refactor(modal)!: rename `width` property to `widthScale`

And a more in-depth, but succinct description for the PR's body summary could include:

Related Issue: <Issue number>
BREAKING CHANGE: For consistency, renames `width` property to `widthScale`.

See the conventional commits doc for more helpful information.

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

By default, the PR body will be used for the commit message when squash merging, so make sure to add any relevant details there.

Visual snapshots

If the PR includes visual changes, once you are ready to run Chromatic to create visual snapshots, add the pr ready for visual snapshots label to the PR. Removing and re-adding the label is required to re-run snapshots, e.g. when pushing additional updates.

If visual snapshots are not necessary for the PR (e.g. changes to doc, ci, storybook, etc.), you can add the skip visual snapshots label instead. The skip visual snapshots label can also be used to prevent re-running Chromatic after pushing minor cleanup changes before merging.