Contribute Code

Become a Design System Contributor

Workday Design regularly release centralized code, assets, components, patterns and guidelines for product teams to use. At the same time, we also need people working on our product teams to contribute their app-level knowledge and solutions back into the central design system, so that our releases are designed with both system and real-world product needs included.

In design system terminology this is called a Hybrid system; which is considered to be the most robust design system model for scaling growth, adoption, learning and cohesion across products; ultimately making things better for everyone making design decisions.

Before You Contribute

Contribution to Sana Canvas Kit does not have to be code-based. Anyone can suggest changes to things such as documentation, processes, and use cases.

If you are contributing code, please take a look at the following sections  to familiarize yourself with how the Sana Canvas Kit repo is organized and run. This will help streamline the pull request process. If you have any questions, please reach out to a member of the Sana Canvas team

If your contribution is visual or UI-based, please ensure you consult with a designer or request a maintainer’s help so the contribution can be evaluated as an end-to-end process.

Types of Code Contribution

Documentation

Documentation is key to providing a great developer experience. We might miss a word, need more context, or have outdated information. In which case, we encourage the community to speak up and add in / update our docs for a better experience. When contributing a documentation update, make sure to create an issue  if one doesn’t exist! A good way to get experience with the codebase without a breaking change is contributing an example that might help improve our docs. These issue will typically have a label of Documentation.

Code Fix

There are times where there’s a bug in our current major version and we have an issue to fix it. This is another great opportunity to put in a patch fix. Often times an issue has been created and we’ll provide a potential solution in a comment. Contributing a code fix is another great way to gain knowledge on a component or utility and helping us out!. These issue will typically have a label of Bug.

Note: In most cases, if we have a Github issue  we’ll label it with Help Wanted or Good First Issue. These issues can range from documentation, to testing, examples, code-rewrite and more.

How to Contribute to Sana Canvas Kit

Communicate on Issues

• Create or identify an issue  to work on
• New contributors are recommended to start with a good first issue 
• Ask our team if the issue is relevant or has attention from other developers
• Communicate if you’d like to work on the issue
• Ask questions! You have our support, and you will always need more information than what is in the issue.

Git Guidelines

All development should happen on a personal fork (including maintainers). Fork the repo  to your personal account, and create a feature branch for each contribution.

Branches

• Create branches for each feature you develop
• Branch names should be a description of the feature being implemented/bug being fixed (i.e. my-feature).
• Prefer dashes over camelCasing in branch names.

We maintain three major versions of Canvas Kit at any given time: the previous major, the current major, and the next major version. These versions live in four branches:

• support - the previous major version - patches only, no new features or breaking changes
• master - the current major version - patches and small updates only
• prerelease/minor - the current major version - new features are added here and released in a new minor version.
• prerelease/major - the next major version - patches, new features, and major breaking changes

Commit Message Format

Sana Canvas Kit relies on the conventional-commit format specification . By formalizing our commit message format, this allows us to easily generate changelogs and scan through the commit history. It also automates semantic versioning .

Best Practices

Pull Requests

• We support creating a Draft Pull Request as soon as you have figured out a working implementation, for early feedback. It can later be marked Ready for Review.
• Open a pull request from a feature branch on your fork against the master branch on the main repository
• When a pull request passes all checks and reviews, a core maintainer merges via Squash and Merge with a link back to the PR
• The branch will automatically be deleted on merge, but its commits and the branch reference are still available via the PR
• When multiple developers collaborate on a PR, project maintainers are able to push commits to fork PRs, but other contributors will need to open their own PRs against the personal fork and the appropriate feature branch.

The Developer Contribution Experience

Storybook Sana Canvas Kit uses Storybook  for the component development environment.

Yarn and Workspaces Sana Canvas Kit uses Yarn for package management and takes advantage of its support for Workspaces  to connect all of its different modules within a single repository. It is recommended but not required over npm, unless you are updating dependencies, then it’s required.

Testing Sana Canvas Kit uses Jest  and React Testing Library  to unit test our React components. Sana Canvas Kit uses Cypress  for UI tests. For info on why we chose Cypress, visit Why Cypress?  For more information about how to write Cypress tests, visit Writing Cypress Tests .

Automation on Commit Upon commit, lint-staged  will run your staged code through Prettier  and eslint .

Releases

• Releases are prepared by updating package versions with lerna version
• A PR is created for the above updates.
• After the release PR is approved and merged, we create a release in GitHub with the contents of the changelog updates.
• The GitHub release automatically tags master with the new version, and deploys the new version to NPM.

Get Started Developing

1. Clone the repository from your fork and run yarn
2. Run yarn start to start Storybook 
3. Visit http://localhost:9001/ 

Create a Module

1. Run yarn create-component
2. Enter in a module name and description
3. (optional) Add any required dependencies on other modules
4. (optional) If you added any extra dependencies, run yarn
5. Start Storybook yarn start
6. Navigate to http://localhost:9001/  and find your new module’s story
7. Begin editing your new React component in modules/react/<MODULE_NAME>/index.ts.

Export a Module

If your module’s index.ts has a default export, make sure it is available as a named export as well. This allows for greater flexibility in how developers consume your module. Note that yarn create-component should set this up for you by default.

Build Modules

yarn build

This will build all modules’ CSS and JS. This should only be done before publishing. It is not needed for development.

Test Modules

yarn test

This will start the unit tests.

Code Style Guide

Rules are enforced using ESLint  and code formatting is provided through Prettier .

To lint using ESLint, use yarn lint. To format and lint your code (careful - this can rewrite files), use yarn format.

Code formatting will occur automatically before git commit for files staged using git add.

Canvas Kit Labs and Preview

While we iterate on a new component’s API, functionality and accessibility, sometimes we want to make it available to consumers ASAP. If we introduced the component normally, this could result in many breaking changes to our codebase. To avoid this, we have introduced Canvas Kit Labs  as a place to incubate components. If there is a lot of debate/discussion/flux happening in your PR and the component is needed right away, it may be moved to this location so it can be made available while we iterate on it. Visit the link above for more info.

Canvas Kit Preview  is for components that have had a full design and a11y review, and are approved for use in product. The API’s and/or underlying architecture could still be subject to change, but not without strong communication and migration strategies. Essentially, Canvas Kit Labs is for alpha components and Canvas Kit Preview is for beta components.

Editors

Visual Studio Code is our preferred IDE. Install the Prettier and ESLint plugins for quicker and easier formatting.

Visual Studio Code

Install prettier-vscode  and vscode-eslint 

Consider adding the following options:

• Format on save 

Sana Canvas Kit Contributor License Agreement

Each Contributor (“You”) represents that such You are legally entitled to submit any Contributions in accordance with these terms and by posting a Contribution, you represent that each of Your Contribution is Your original creation.

You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.