IBMers should complete steps documented on W3 Developer before contributing to open source projects.
Also refer to contributing in Carbon.
Contribution comes in many forms and many of them do not need you to write a line of code.
- Have a question? Visit our Slack channel and/or ask a question on GitHub
- Have an issue you’d like resolved, then raise an issue
- Have a new component, pattern, or enhancement request, then tell us about it
There’s only so many hours in a day, so we welcome contributions of code. Find an issue or raise one, and follow the guide below.
Go to the Carbon for IBM Products repository on GitHub and fork the repo, syncing with the original repo.
When contributing to Carbon for IBM Products, your work should always be done in a branch off your fork.
- To install the project’s dependencies, from the root directory of your fork,
run
yarn
- To scaffold a new component or pattern, run
yarn generate ComponentName
, whereComponentName
is the name of the component or pattern - To get your development server running and to start coding, run
yarn storybook
This will start a development server where you can see any changes you are making to components in our Storybook.
The command to start the server will differ depending on which package you are
working within. To find out which command you’ll need to run, you can check the
scripts
property in the package’s package.json
.
Once it's done building, you can edit source code or create new components. The
system is set up to automatically bundle your additions / changes. Visit
http://localhost:3000
to see the changes happen on
the fly.
The Canary lines in the components were added to enable component feature flags, that is, the enabling of components through user settings.
This allowed the removal of the term/package experimental
and permitted the
publication of all components in a single package. Those that have not yet
completed the release review
process are considered to be canary
and require the consumer to enable via a
feature flag.
See example component enabled via feature flags on CodeSandbox.
For more information on how this affects components see CANARY_STRUCTURE.md.
If you’re contributing to our JavaScript code, test your changes by running
yarn test
.
Tests are written in React Testing Library.
User Experience Standards Adopter Guide.
Note: Before you make a pull request, search the issues to see if a similar issue has already been submitted. If a similar issue has been submitted, assign yourself or ask to be assigned to the issue by posting a comment. If the issue does not exist, please make a new issue.
Note 2: If you are submitting a new component or pattern there are some
additional steps we’d like you to take. In brief, use the
New component or pattern
issue template. The new issue should be an epic.
Refer to contributing in Carbon for some contribution quick tips.
An effective pull request should not have more than 400 lines of code changed1, so do not create one massive PR if it can be scoped down into smaller, focused PRs of independent behaviors and functionality.
When you’re at a good stopping place and you’re ready for feedback from other contributors and maintainers, commit, push to your fork, and create a pull request.
- See Conventional Commits for more information about how to write your commit message.
- Also refer to How to write the perfect pull request.
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, use the same method detailed above.
Once all revisions to your pull request are complete, a maintainer will squash and merge your commits for you.
If you introduce a new dependency to package.json
then there will be some
additional work to do.
- Verify the dependency has previously been pedigree reviewed
- Verify the dependency doesn’t contain any vulnerabilities
- Verify the dependency bundle size is acceptable
- Verify the dependency is actively maintained
If you create a new component or pattern, it should first be contributed as
canary
.
Due to the nature of the monorepo, when you add a new component or pattern, be
sure to add it in packages/core/story-structure
. This step will surface the
component or pattern in the Storybook navigation.
To move a component from canary
to the released state, there are two
additional tasks that must be completed.
- See our
design review guidelines
and then create a new issue based on the
design-review
template and complete the steps suggested. - See our
release guidelines
and then create a new issue based on the
release-review
template.