Skip to content

Latest commit

 

History

History
102 lines (66 loc) · 5.45 KB

CONTRIBUTING.md

File metadata and controls

102 lines (66 loc) · 5.45 KB

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

I want to contribute, what should I work on?

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

  • Adding ideas for components to out wishlist project We are using the wishlist to gather ideas about what components teams are using that we might be able to reproduce as a part of Calcite Components.
  • If you want to help develop components take a look at out 1.0.0 components which are the components we are targeting for the first release of Calcite Components. Before starting development please review our component conventions and the Stencil documentation.

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

Before filing an issue

If something isn't working the way you expected, please take a look at previously logged issues first. Have you found a new bug? Want to request a new feature? We'd love to hear from you.

Please include the following information in your issue:

  • Browser (or Node.js) version
  • A snippet of code
  • an explanation of
    • What you saw
    • What you expected to see

Getting a development environment set up

You don't have to but we recommend installing TypeScript, TSLint, Prettier and EditorConfig extensions for your editor of choice.

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 to add and test your new component. Just add another <calcite-tab>and <calcite-tab-title> and start working.

Adding a new component

Before adding a new component, have a 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 exist already.

Running the tests

npm test will run the current test suite.

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

Please refer to the Stencil testing documentation for more information.

Documenting a component

Calcite Components utilizes Storybook for documenting components. Adding a new component is very simple:

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

The storybook 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 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 })`

Deploying documentation

We deploy the docs with storybook deployer.

  1. Make sure your changes have landed in master
  2. Use npm run deploy to build the components, build the docs, and deploy to gh-pages

Release process

To release a new version of Calcite Components you must:

  1. Be a member of the @esri organization on npm.
  2. Be a member of the admin team for Calcite Components.
  3. Make sure you have a remote named origin pointing to Esri/calcite-components.
  4. Run npm run release:prepare. This script will:
  • Create a build
  • Run all the tests
  • Update the package version
  • Create a changelog entry for the current release
  • Create a commit and tag it - ⚠️ Note if you need to make changes after this step, make sure to amend the commit (git commit --amend) and recreate the tag (git tag --force <version>)
  1. Run npm run release:publish. This script will:
  • Push the release tag to the repo
  • Publish to NPM
  • Publish to GitHub (including source and package)