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
Fork
button in the top-right corner.After it’s finished, click on the
Clone or Download
button and copy the contents.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
origin
is set to your fork by default. You’ll want to add a remote that points to the upstream repo.
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
to install all of the projects dependencies.
This project has two packages: the actual theme package (gatsby-theme-carbon
)
and the example
package. The example package emulates a project which uses the
theme. Its only dependencies are Gatsby, React, and the adjacent theme package.
The example
package also serves as the theme’s documentation and
website; it’s deployed on every merge
to main.
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
yarn dev
– start the development environmentyarn dev:clean
– clear cache and restart devyarn format
– format your code with prettieryarn lint
- check for errors in your javascriptyarn test:prefix
– build and serve with a path 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
file will be
supplied with all of the Carbon Sass
variables:
color, spacing, theme, and motion, as well as type and layout mixins, are
imported automatically.
You should colocate your stylesheet with the component(s) that import it. If the
component is TreeView
then the stylesheet should be TreeView.module.scss
.
All contained within the TreeView
directory.
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
file.
TreeView.module.scss.treeView {color: $text-01;}
TreeView.jsimport { treeView } from './style.css';const TreeView = (props) => <