Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
102 lines (67 loc) · 5.11 KB

CONTRIBUTING.md

File metadata and controls

102 lines (67 loc) · 5.11 KB

Design Tokens Community Group

This repository (or “repo”) is used for work in the Design Tokens Community Group, governed by the W3C Community License Agreement (CLA). To make substantive contributions, you must join the Community Group.

For more details, read the Contribution Mechanics section of the community group's charter.

If you are not the sole contributor to a contribution (pull request), please identify all contributors in the pull request comment.

To add a contributor (other than yourself, that's automatic), mark them one per line as follows:

+ @github_username

If you added a contributor by mistake, you can remove them in a comment with:

- @github_username

If you are making a pull request on behalf of someone else but you had no part in designing the feature, you can remove yourself with the above syntax.

Local development

The following section is for previewing designtokens.org and the technical reports on your local machine.

Setup

This repo requires Node.js (if you need to manage multiple versions of Node.js, fnm is highly-recommended) and pnpm installed. With both installed, clone this repository locally, and in a terminal run in the project root:

pnpm i
pnpm run install-browsers
pnpm run dev

The local site will be available at localhost:4321.

Commands

The following commands can be run from the project root:

Command Description
pnpm run dev Run designtokens.org locally in development mode.
pnpm run lint Lint the project.
pnpm run spellcheck Run spellcheck.
pnpm run build Make a static build of the website.

Note

You’ll also find pnpm run dev commands both in www and technical-reports folders. Those should only be used for debugging purposes, as they only run part of the workflow.

Project structure

This repo contains the following sub-directories that house different projects:

Directory Description
meeting-notes/ Notes from past meetings.
technical-reports/ The design tokens specification.
www/ The designtokens.org code.

Spellcheck

This project uses cSpell for spell checking. The spellcheck is case-sensitive, so it will detect when words like Bézier or GitHub need proper capitalization.

Words may be globally allowed or globally blocked by adding to the cspell/ folder. See the cSpell documentation on dictionaries for more info.

To override instances without adding to the list, either add a // cSpell: disable comment or // cSpell:words [list of comma-separated words] comment. See the [cSpell documentation on overrides]https://cspell.org/docs/Configuration/document-settings#words) for more info.

Publishing a report

Note

This should only be done by a spec editor.

These are the general steps to cut a new release of the report.

Setup

The following steps clean, update, and get your local copy into an ideal state. This prevents errors while publishing such as corrupted caches, as well as any accidental local files that should not be part of the new version.

  1. Pull latest: git pull
  2. Reset your local repo (optional but recommended): git clean -dfx (⚠️ this will erase any files not tracked in git, so if you have any temporary files you want to keep, move them out of the repo first).
  3. Reinstall deps: pnpm i

Versioning

  1. Update ReSpec: Update the information in technical-reports/TR/index.html, as well as all other reports. Things include, but aren’t limited to:
  2. Run a build: pnpm run build
  3. Rename: Rename www/src/pages/TR/drafts to www/src/pages/TR/[new version]. Be sure to commit this folder!
  4. Update table: Update www/src/pages/technical-reports.md

At the end of this you should see changes you can commit in www/src/pages/TR/[new version]. This will now be a permanent version, and every change will be tracked manually.