Graupl Logo

Contributing to Graupl ​

Read these guidelines before contributing code, documentation, bug reports, or feature requests.

Write for the people who use and maintain this project ​

Graupl is part of Accessible Ecosystem and helps people who may use the web differently than we do. Contributions should reflect the same care we put into making the web more accessible and friendly for everyone.

Accessibility also includes the people reading our code and documentation. Write plainly so someone just entering the field can follow your work, while giving experienced developers the detail they need to understand and maintain it.

  • Use descriptive names, clear steps, and straightforward conditions. Avoid clever shortcuts that make the code harder to understand.
  • Follow the project's existing structure and conventions. Introduce shared code when it makes the behavior easier to follow, rather than simply reducing the number of lines.
  • Explain decisions and behavior that are not obvious. Keep comments useful, and update affected documentation when behavior changes.
  • Keep contributions focused on the problem they address. Avoid unrelated cleanup or refactoring.
  • Preserve existing behavior unless the contribution intentionally changes it. Consider keyboard interactions, focus, events, and compatibility.
  • Use the relevant accessibility standards and ARIA Authoring Practices Guide patterns when changing accessibility behavior. Check HTML examples and generated markup for validity.
  • Test the behavior your contribution affects. Passing automated checks alone does not establish that an interaction is accessible.

By submitting any contribution, you take responsibility for its contents, whether you wrote it yourself or used assistance. Submit work you understand, have reviewed, and can explain.

Read the project instructions and accessibility policy before contributing. AI-assisted contributions must also follow the AI contribution policy.

Where to contribute ​

We use GitHub to host code, track bugs and feature requests, and review pull requests. Use GitHub issues and pull requests so project discussions and decisions are available to contributors.

Submit a pull request ​

All code changes happen through pull requests.

  1. Fork the repository and create your branch from 1.x.
  2. Make your changes and update any affected documentation.
  3. Add or update tests that demonstrate the intended behavior where the change needs test coverage.
  4. Run the relevant tests and code checks described below. Verify the affected behavior yourself.
  5. Open your pull request and link any relevant issues. Describe the change, how you verified it, and any remaining limitations.

Contribution license ​

Contributions must use the same license as the project, GNU General Public License v3.0 or later, identified as GPL-3.0-or-later in package.json.

Report a bug ​

Report bugs by opening a GitHub issue.

Include the following in your bug report:

  • A summary of the problem.
  • Steps to reproduce it, with a small code example if possible.
  • What you expected to happen.
  • What actually happened.
  • Any relevant background, such as your browser, package version, and anything you have already tried.

Set up and check your changes ​

Use Node.js 24, which is also used by the project workflows. Run npm install to install the development tools.

Run commands from the repository root. Graupl uses npm workspaces under packages/. Keep JavaScript component code in packages/core/src/js/ or the package that owns the component. Shared Sass lives in packages/core/src/scss/ and packages/core/scss/; check the existing files before adding styles. Keep tests in tests/. Name unit tests .unit.test.js and browser tests .browser.test.js.

The project uses ESLint, Prettier, and JSDoc for JavaScript, and Stylelint, Prettier, and the configured Sass guidelines for styles.

Check your code without changing files:

shell
npm run eslint
npm run stylelint
npm run prettier -- --check

To apply automatic fixes and formatting, run:

shell
npm run lint

Review the resulting changes. Automatic fixes do not resolve every issue. Code must pass the project's linting and formatting checks before it can be merged.

Run the unit tests:

shell
npm run test:unit

For browser tests, install the Playwright browsers and run the browser suite:

shell
npx playwright install
npm run test:browser

Browser screenshot baselines are maintained in the Linux environment used by CI. Review visual differences before updating them.

Build the affected output:

shell
npm run build
npm run build:packages

The root build also builds the documentation and demo. For documentation-only changes, run npm run docs:build. npm run demo:build builds the demo separately. Package builds regenerate each workspace package's output. Review generated changes along with source changes.

Also verify the behavior your change affects, including keyboard interaction, focus, and assistive-technology behavior where applicable. Automated tests alone do not establish that an interaction is accessible.

Changes involving Core ​

When changing the Core dependency or behavior inherited from Core, verify the affected component behavior with the Core version this project will use. State whether you tested against a published package or a local checkout.

Core's dependent-project testing guidance explains how its workflow tests projects against proposed Core changes. Those results cover only the behavior the dependent tests exercise.

Commit guidelines ​

Write commit messages using Conventional Commits. For example:

text
fix: cancel pending callbacks when disposing a component

The format is:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

See the specification for commit types, optional scopes, and how to describe breaking changes.

You can use Commitizen to write a commit message through guided prompts:

shell
npm run commit

Commit messages must follow this format before a contribution can be merged.

References ​

This document was adapted from the open-source contribution guidelines for Facebook's Draft

Attribution ​

This document is based on Accessible Ecosystem Core, adapted from its corresponding document.