Skip to content

Latest commit

 

History

History
127 lines (105 loc) · 5.12 KB

CONTRIBUTING.md

File metadata and controls

127 lines (105 loc) · 5.12 KB
Raw

Contributing to Garden

Keen to contribute to Garden? We're stoked to have you join us. You may find that opening an issue is the best way to get a conversation started. When you're ready to submit a pull request, follow the steps below. We follow a code of conduct as our guide for community behavior.

This is a multi-package repo which uses Lerna to manage shared and cross-package dependencies. The basic repo layout includes:

  • ├── package.json – the top-level "project" package that contains the dependencies and scripts needed to manage the multi-package repo. This package will never be published to the registry.
  • ├── packages/ – the folder that contains individual @zendeskgarden packages which are published to the registry.
    │ ├── buttons/
    │ ├── tabs/
    │ └── etc.
  • └── demo/ – HTML pages used to test and demonstrate CSS component styling.

Garden CSS source is transformed via PostCSS. This allows us to leverage future CSS syntax (via the PostCSS-cssnext plugin), yet publish browser-compatible CSS distributions.

Garden CSS selectors use a form of BEM (Block Element Modifier) naming. The naming convention follows a pattern:

.block {
}
.block__element {
}
.block--modifier {
}
  • .block represents a high-level component.
  • .block__element represents a descendant element of the .block.
  • .block--modifier represents a style variation of .block.

In addition, Garden CSS incorporates namespace prefixes to encourage self-documenting transparency. For example:

.c-btn--pill /* a pill-styled button Component */
/* a pill-styled button Component */
.u-jitterfix /* the jitterfix Utility */
.is-active; /* a stateful namespace to indicate transient styling */

Check out the Namespaces post for more detail on these conventions.

Versioning Workflow

Garden follows semantic versioning. We release patch versions for bugfixes, minor versions for new features, and major versions for any breaking changes.

The pull request workflow along with the PR template will help us determine how to version your contributions.

All changes are recorded in applicable package CHANGELOG files.

Development Workflow

After you clone this repo, run npm i to install dependencies needed for development. A git post-checkout and post-merge hook will automatically npm i in order to keep your development environment up to date as you checkout and merge between branches. After installation, the following commands are available:

  • npm start* to launch component demo server with live reload – package source files will be watched for changes.
  • npm test* to run tests across all component packages. Note this is run as a git pre-push hook for all packages that have changed since the last release.
  • npm run lint* to enforce consistent CSS and JavaScript code conventions across all component packages. Note this is run as a git pre-commit hook.
  • npm run format* to enforce code style with opinionated formats (i.e. package.json) across all component packages. Note this is run as a git pre-commit hook.
  • npm run build* to rebuild distributions across all packages. The build runs as part of the initial install.

* Operates as a facade over a Lerna command; operation may be modified using option flags (i.e. scope, since, or ignore).

Pull Request Workflow

  1. Fork the repo and create a branch. Format your branch name as username/verb-noun.
  2. If you haven't yet, get comfortable with the development environment.
  3. Regularly git commit locally and git push to the remote branch. Use whatever casual commit messaging you find suitable. We'll help you apply an appropriate squashed conventional commit message when it's time to merge to the main branch.
  4. If your changes result in a major modification, be sure all documentation is up-to-date.
  5. When your branch is ready, open a new pull request via GitHub. The repo PR template will guide you toward describing your contribution in a format that is ultimately suitable for a structured conventional commit (used to automatically advance published package versions).
  6. Every PR must pass CI checks and receive at least one 👍 to be considered for merge.
  7. Garden maintainers will manage the squashed merge to the main branch, using your PR title and description as the scope, description, and body for a conventional commit.

License

By contributing to Garden, you agree that your contributions will be licensed under the Apache License, Version 2.0.