Our repository requires that a forked repo is used for any work before contributing back to the repository. This includes regular team members/maintainers.
-
Fork the project by navigating to the main repository and clicking the Fork button on the top-right corner.
-
Navigate to your forked repository and copy the SSH url. Clone your fork by running the following in your terminal:
$ git clone git@github.com:{ YOUR_USERNAME }/carbon-for-ibm-dotcom.git $ cd carbon-for-ibm-dotcomSee GitHub docs for more details on forking a repository.
-
Once cloned, you will see
originas your default remote, pointing to your personal forked repository. Add a remote namedupstreampointing to the maincarbon-for-ibm-dotcom:$ git remote add upstream git@github.com:carbon-design-system/carbon-for-ibm-dotcom.git $ git remote -v -
Switch to our version of Node. The currently supported node versions are listed within the package.json file under the "engines" key.
Carbon for IBM.com is built using a collection of packages all built in the same git repository. You might have heard this setup described as a monorepo.
As a result, we use two pieces of tooling to help us managing installing dependencies and publishing our packages. These include:
- Yarn workspaces for handling dependencies across all packages
- Lerna for publishing packages, tagging versions, and more
In order for you to install all the dependencies in this project, you'll need to install Yarn and run the following command in your terminal:
yarn installThis will install all of the dependencies for every package in our project. In addition, it allows us to link between packages that we are developing.
This strategy is particularly useful during development, and tooling like Lerna will pick up on when packages are linked in this way and will automatically update versions when publishing new versions of packages.
Next up, you'll most likely want to build all of the package files so that things don't fail while you are working on a package. To do this, you can run the following command:
yarn buildAfterwards, you should be good to go! For more information about how we handle dependencies, definitely take a look at our write-up here.
While working on Carbon for IBM.com, here are some of the top-level tasks that you might want to run:
| Command | Usage |
|---|---|
yarn build |
Uses lerna to run the build script in each package |
yarn clean |
Resets the state of the project by removing all node_modules and running the clean script in each package |
yarn doctoc |
Runs doctoc on all files in the doctoc directory |
yarn format, yarn format:diff |
Format files using prettier, check if files have been formatted |
yarn reset |
Cleans the yarn cache and node_modules folders and brings the project back to a stable state |
In addition, you can use yarn to run bin files using the yarn <bin>
syntax. For example, if you wanted to use lerna to run a script in every
package you could do the following:
# Access $(yarn bin)/lerna and pass `run build` to the executable
yarn lerna run buildThere would be instances where in development, testing one of the packages before
publishing would be required. Creating a symlink to the local package is typically
the best way to approach this, using yarn link:
https://yarnpkg.com/lang/en/docs/cli/link/
-
Pull the latest main branch from
upstream:$ git pull upstream main -
Always work and submit pull requests from a branch. Do not submit pull requests from the
mainbranch of your fork.$ git checkout -b { YOUR_BRANCH_NAME } main -
Create your patch or feature.
-
Test your branch and add new test cases where appropriate.
-
Commit your changes using a descriptive commit message.
$ git commit -a -m "chore: Update header with newest designs, resolves #123"Note: the optional commit -a command line option will automatically "add" and "rm" edited files. See Close a commit via commit message and writing good commit messages for more details on commit messages.
Carbon for IBM.com also uses a commit format called Conventional Commits. This format is used to help automate details about our project and how it changes. When committing changes, there will be a tool that automatically looks at commits and will check to see if the commit matches the format defined by Conventional Commits.
-
Once ready for feedback from other contributors and maintainers, push your commits to your fork (be sure to run
yarn ci-checkbefore pushing, to make sure your code passes linting and unit tests):$ git push origin { YOUR_BRANCH_NAME } -
In Github, navigate to carbon-design-system/carbon-for-ibm-dotcom and click the button that reads "Compare & pull request".
-
Write a title and description, then click "Create pull request".
See how to write the perfect pull request for more details on writing good PRs.
-
Stay up to date with the activity in your pull request. Maintainers will be reviewing your work and making comments, asking questions and suggesting changes to be made before they merge your code. When you need to make a change, add, commit and push to your branch normally.
Once all revisions to your pull request are complete, a maintainer will squash and merge your commits for you.
Most likely this is due to Yarn mistakenly removing, or forgetting to add, a dependency to our offline mirror. Typically, running the following set of commands should reset the project back to a valid state and should bring back any missing dependencies or fetch new ones.
yarn cache clean
yarn clean
yarn install
yarn buildA shortcut task available from the root also runs the above commands:
yarn resetIt is possible that a newly introduced package is added to this monorepo, but packages/newpackage is not linked in node_modules. While a yarn reset may resolve this, another possible way is to run:
yarn install --force