Change Workflow

Change categories

Every change to Spark will have tasks that fall into at least one of these categrories. Often a change will have tasks in many or all of them. The four categories are: Research, Design, Build, and Document.

We use GitHub issue titles to indicate which category an issue relates to. The format of issue titles looks like this:

[DESIGN] Create mockups for kitten component

1. Research

Research tasks can take many forms. They can be anything from user testing to diving in to a new technology. Research tasks should have an outcome that can be shared so that decisions can be made or additional taks can be created. If you are doing any kind of research, this category is for you.

• Research issue titles must begin with [Research]
• The results of your research should be shared with the core Spark team.
• A Research task is complete when a decision has been made by the core team about the next steps.
• If a Design, Build, or Document task is required, that issue should be created at this point.

2. Design

Design tasks apply to visual or interaction changes. These tasks include things like creating wireframes for a new component, sketching out a change to an interaction, or designing a new icon.

• Design issue titles must begin with [Design]
• Designs can be created in whatever software is appropriate, like Sketch, Illustrator, or Invision.
• Design tasks must follow the Contribution Guide.
• Brand new design ideas should be shared with the broader design community for critique and to validate its usefulness across products.
• Design work must be approved by Spark's design lead and should be reviewed by an engineer on the core team if the task will require engineering work.
• Finished Design tasks need to be added to the design toolkit. these changes should follow the Build task process outlined below.
• If a Build or Document task is required and doesn't already exist, it should be created at this point.

3. Build

Build tasks apply to any changes made in code. These can be changes to components, to the Spark Docs site, or to any tooling that is part of the system.

• Build issue titles must begin with [Build]
• Code changes must follow the guidelines in Getting Started - Developers for code style.
• Build tasks must follow the Contribution Guide.
• Code changes must be approved by a member of Spark's core team and should be reviewed by Spark's design lead when design or interaction are affected.
• If a Document task is required and doesn't already exist, it should be created at this point.

Process

Follow this process for making code changes.

• Fork the project on GitHub.
• Create a new feature branch in your fork off of the "staging" branch. Give the branch a descriptive name.
• Once you have made your first commit, open a PR against the "staging" branch of the main Spark repo and add the "status: DO NOT MERGE" label. You should also describe the changes you are making in the description field of the PR.
• Remember to commit regularly and push those commits to your fork so that the PR is always up to date. This allows others to begin reviewing and commenting on the changes you are making.
• If you are making changes to JS code, you must include unit tests. Spark strives for 100% test coverage. Commits to your PR will automatically trigger unit test coverage checks. To check during development, run:
  npm run coverage
  in the spark-core or spark-extra directories.
• In addition to the code for the feature and unit tests, each component has a test page available at "/tests/[component-name]". For example: sparkdesignsystem.com/tests/tables. You will need to create this page for any new components or update the existing page if you are adding new versions of a component. If you need help with this, reach out to the Spark Team.
• The Spark core team is untimately responsible for the quality of any code changes, but all contributors are expected to test their changes thoroughly. This includes browser testing, unit testing, and testing the different states that the change might affect (e.g. error, empty, etc.)
• When you are ready for your PR to be merged, remove the "status: DO NOT MERGE" label, add the "status: PR review" label, and notify the Spark Team.
• In order to merge a PR into "staging", at least one memeber of the Spark core team must approve the changes in GitHub.

4. Document

Document tasks apply to any content that communicates what Spark provides or how it works. This includes images, code examples, copy, and any other content that helps users understand how Spark works. When Document tasks are the result of Research, Design, or Build tasks, the work is typically done by the designer or engineer who performed the other tasks.

• Document issue titles must begin with [Document]
• Documentation should be completed on the appropriate page within the Spark Docs site. This could be on a component page, in the "Getting Started" section, or in the "Documentation" section.
• Build tasks must follow the Contribution Guide.
• When you finish adding your documentation, you will follow the same process. As the Build task in order to open a PR and get the documentation reviewed.
• If you are a designer or other contributor who is uncomfortable with GitHub or making changes within code, please reach out to the Spark Team so you can be paired with an engineer. In these cases, you can write your documentation in One Note, Google Drive, or in another word processor and work with an engineer to add the changes.
• Documentation changes must be reviewed by a member of the Spark core team.

Issue labels

Spark has a number of issue labels available on GitHub. These should be applied to every issue for easier prioritization and filtering. The labels are divided into 4 categories: scope, type, status, and js.

At a minimum, every issue should include a scope and type label. Each label has a description next to it for when it should be used.