Contributions
Use this guide to contribute to the theme. We’ll show you how to get the development environment set up as quickly as possible, so you can start contributing.
Project setup
-
Go to gatsby-theme-carbon and click the
button in the top-right corner.Fork -
After it’s finished, click on the
button and copy the contents.Clone or Download -
In your terminal, clone the repo into your directory of choice
git clone [PASTE_URL_HERE]cd gatsby-theme-carbon
- When you clone your forked repo the is set to your fork by default. You’ll want to add a remote that points to the upstream repo.origin
git remote add upstream git@github.com:carbon-design-system/gatsby-theme-carbon.git
- In your terminal, verify that the remotes have been set
git remote -v
Development
We use yarn and yarn workspaces to develop the Carbon Gatsby theme. This allows us to have a development environment that’s closely linked to the theme with minimal setup. Run
yarn install
This project has two packages: the actual theme package (
gatsby-theme-carbon
example
example
New theme development will happen in the theme package while documentation and testing of that change will occur through changes in the example directory.
Development scripts
- – start the development environmentyarn dev
- – clear cache and restart devyarn dev:clean
- – format your code with prettieryarn format
- - check for errors in your javascriptyarn lint
- – build and serve with a path prefixyarn test:prefix
Work in a branch
You should always start a new project by pulling upstream changes into main and then creating a new branch. This workflow ensures you don’t accidentally commit anything to your main branch and get stuck when trying to open a pull request.
git checkout maingit pull upstream maingit checkout -b my-branch-name
Commit messages
For commit messages we use Angular commit conventions to dictate whether a commit is for a feature, fix, docs, etc. You need to prefix your commits with one of the following:
- feat (feature)
- fix (bug fix)
- docs (documentation)
- style (formatting, missing semi colons, …)
- refactor
- test (when adding missing tests)
- chore (maintain)
git commit -m "chore: this is a test commit message"
Opening a Pull request
When you’re ready to open a pull request, push to your origin remote.
git push origin my-branch-name
You’ll get a message in your terminal with a URL to open up a pull request in the upstream repository. Navigate to that URL and be sure to give a detailed summary of your pull request in the title and body section of the form.
Sass and CSS Modules
For internal theme components we use Sass and CSS Modules. This allows us to take advantage of the Carbon Design System resources while not worrying about className collisions. By default, each
.scss
You should colocate your stylesheet with the component(s) that import it. If the component is
TreeView
TreeView.module.scss
TreeView
CSS Modules
You don’t need to prefix your classes as CSS Modules will generate unique class names for you. Import the class from the
.scss
.treeView {color: $text-01;}
import { treeView } from './style.css';const TreeView = (props) => <div className={treeView} />;
For conditionally applying class names, use the
classname
cx
"long"
long
import cx from 'classname';import { treeView, long } from './style.css';const TreeView = (props) => {const className = cx(treeView, {[long]: props.long,});const TreeView = (props) => <div className={className} />;};
If you need to target a global class not processed by CSS Modules, you can do so with the global selector.
:global(.cds--grid) .codeBlock {@include type-style('code-01');}
VS Code
To get linting error feedback while writing javascript and SCSS in VS Code, install the stylelint and ESlint extensions. We use ESLint’s Prettier rules to format and lint all of our JavaScript in one pass. To get your code to format properly on save, add the following to a
.vscode/settings.json
{"editor.formatOnSave": true,"[javascript]": {"editor.formatOnSave": false},"[javascriptreact]": {"editor.formatOnSave": false},"eslint.autoFixOnSave": true,
To lint the entire project and get errors in your
Problems
.vscode/tasks.json
cmd+shift+d
{"version": "2.0.0","tasks": [{"type": "npm","script": "lint:js","problemMatcher": "$eslint-stylish"},{
Test pages
If you want to add examples of what you are working on or see changes you’ve made, you can add an MDX file to
packages/src/pages/test
(your-server-name)/test/(added-file)
/test
- : use this page to test spacing around components when combined in common patterns.Spacing audit
Publishing
- Pull the latest from the main branch, usually by running
on your local machine.git pull upstream main
- From the root of the package run .yarn release
- Follow the prompts accordingly.
- In the project’s release tab, edit the new release to include a summary of new changes.