carbon-components-svelte/CONTRIBUTING.md

Contributing

Before submitting a pull request (PR), consider filing an issue to gain clarity and direction.

• Prerequisites
• Project set-up
  • Install
• Documentation set-up
• Development workflow
  • Component Format
  • Editing a component
  • Creating a component
  • Run npm run build:docs
• Submit a Pull Request
  • Sync Your Fork
  • Submit a PR

Prerequisites

• Node.js (version >=18)
• npm (bundled with Node.js)

Project set-up

Fork the repo and clone your fork:

git clone <YOUR_FORK>
cd carbon-components-svelte

Set the original repository as the upstream:

git remote add upstream git@github.com:carbon-design-system/carbon-components-svelte.git
# verify that the upstream is added
git remote -v

Install

Install the project dependencies:

# carbon-components-svelte/
npm install

Documentation set-up

Component documentation is located in the docs folder. The website is built using svite, routify, and MDsveX. You will need to create a symbolic project link in order to see live changes reflected when developing locally.

First, create a symbolic link at the root of the project folder:

# carbon-components-svelte/
npm link

Go into the docs folder:

cd docs

Link "carbon-components-svelte":

npm link "carbon-components-svelte"
npm install

If linked correctly, any change to a component in the src folder should be reflected in the docs site.

---

Development workflow

Create a topic branch from master. Keep your PR focused and branch up-to-date with upstream master.

git checkout -b new-feature

Preview changes to components from the src folder in the documentation website located in docs/.

In the docs folder, run:

npm run dev

The site should be served at http://localhost:3000/ (or the next available port).

Component Format

Each component should adopt the following structure:

src/Component
│
└───Component.svelte // main component
└───ComponentSkeleton.svelte // Skeleton component (if applicable)
└───index.js // export components

Editing a component

If adding or editing an exported component prop, be sure to annotate its value using JSDoc conventions.

/**
 * Specify the size of the component
 * @type {"sm" | "default" | "lg"}
 */
export let size = "default";

Creating a component

First, submit an issue.

If creating a new component, don't forget it from src/index.js:

export { CopyButton } from "./CopyButton";
export { ComboBox } from "./ComboBox";
+ export { FixedComboBox } from "./FixedComboBox";
export {
  ComposedModal,
  ModalHeader,
  ModalBody,
  ModalFooter,
} from "./ComposedModal";

Run npm run build:docs

Run the following command to re-generate TypeScript definitions and documentation.

# carbon-components-svelte/
npm run build:docs

Submit a Pull Request

Sync Your Fork

Before submitting a pull request, make sure your fork is up to date with the latest upstream changes.

git fetch upstream
git checkout master
git merge upstream/master

Submit a PR

After you've pushed your changes to remote, submit your PR. Make sure you are comparing <YOUR_USER_ID>/feature to origin/master.

Maintainer guide

The following items only apply to project maintainers.

Release

This library is published to NPM with provenance via a GitHub workflow.

The workflow is automatically triggered when pushing a tag that begins with v (e.g., v0.81.1).

However, maintainers must perform a few things in preparation for a release.

Locally, while on master and the branch is clean, run npm run release. This command will:

• Bump the semantic version in package.json
• Generate notes in CHANGELOG.md
• Run npm run build:docs to update the generated documentation

This command will not create a commit nor tag. Afterwards, perform the following manually:

# 1. Commit the changes using the new version as the commit message.
git commit -am "v0.81.1"

# 2. Create a tag.
git tag v0.81.1

# 3. Push the tag to the remote.
# This will trigger the `release.yml` workflow to publish a new package to NPM (with provenance).
git push origin v0.81.1

If all goes as expected, the release.yml workflow should trigger a new run and publish the new version to NPM.

Post-release checklist

After confirming that the new release is published to NPM, perform the following:

1. Create a new release on GitHub. Click "Generate release notes" to automatically list changes by commit with the relevant Pull Request and author metadata. You may manually remove notes that are not relevant to the release (e.g., CI changes).

2. Publish the release as the latest release.

3. As good practice, visit the Pull Request and/or issue for each commit and manually confirm that it's been released. This is helpful for future readers to understand what version includes the new feature or fix.

Released in [v0.81.1](https://github.com/carbon-design-system/carbon-components-svelte/releases/tag/v0.81.1).