Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
166 lines (114 loc) · 5.38 KB

CONTRIBUTING.md

File metadata and controls

166 lines (114 loc) · 5.38 KB
Raw

Contributing to data-viz-wordpress

Thank you for your interest in contributing. This project is maintained by Development Gateway and welcomes contributions from the community.

This is a pnpm monorepo containing WordPress plugins, shared npm packages, and CLI tools for data visualization on WordPress.

Published packages:

Table of Contents

Development Setup

Prerequisites

  • Node.js v22+
  • pnpm v10+
  • Docker (needed to run the full WordPress stack locally)

Install

git clone --recurse-submodules git@github.com:devgateway/data-viz-wordpress.git
cd data-viz-wordpress
pnpm install

Build all packages

pnpm build

Build only published npm packages

pnpm build:npm-packages

Run the full WordPress stack

docker compose up -d

Branching Model

  • main is the stable branch and the base for all pull requests.
  • Create a branch off main for every change, using a prefix that matches the Conventional Commits type:
    • feat/short-description
    • fix/short-description
    • chore/short-description
    • docs/short-description
    • refactor/short-description
    • ci/short-description
  • For long-running project integrations use project/short-description (see below).
  • Do not push directly to main.

Long-running project branches

Projects that contribute work incrementally over time can maintain a project/ branch and merge into main via PR when ready. Use a generic description with no client name or internal identifier — e.g. project/multilingual-blocks, project/superset-embedded-charts. All commits on a project/ branch must follow the same conventions as any other branch. Only generic, reusable code belongs here — client-specific customisations must stay in the project's own private repository.

Making Changes

Adding a changeset

Every PR that changes a published package must include a changeset:

pnpm changeset

Select the affected packages, choose the bump type (major / minor / patch), and write a one-line description for the changelog. Commit the generated file alongside your changes.

Change type Bump
Breaking API change major
New component, hook, or feature minor
Bug fix, refactor, dependency update patch

Changes to plugins/ that are not published to npm do not need a changeset.

Commit Messages

This project follows Conventional Commits. Use a prefix that reflects the nature of the change:

Prefix When to use
feat: New block, component, hook, or user-facing feature
fix: Bug fix
chore: Dependency update, tooling, config
docs: Documentation only
refactor: Code restructure with no behaviour change
ci: CI/CD workflow changes

For breaking changes append ! to the prefix, and add a BREAKING CHANGE: footer in the commit body:

feat(dvz-wp-commons)!: rename block attribute

BREAKING CHANGE: the `dataSource` attribute on FilterBlock has been renamed to `data-source`

Examples:

feat(dvz-wp-commons): add grouped-bar chart block
fix(wp-react-blocks-plugin): correct SSR guard in usePost
chore: upgrade @wordpress/scripts to 30.1.0
ci: add changeset check to test-pr workflow

Code Style

  • TypeScript for all new source files in published packages
  • Keep components generic — no application-specific or client-specific logic
  • No inline comments unless the reason is non-obvious
  • Keep blocks and components focused; avoid adding features beyond what the PR describes

Opening a Pull Request

Forking is not enabled on this repository. To contribute, request access from a maintainer, then create a branch directly in this repo off main.

  1. Create a branch off main (see Branching Model)
  2. Make your changes and add a changeset if a published package was modified (see above)
  3. Ensure pnpm build passes locally — CI runs the same check
  4. Open a PR against main with a clear description of what changed and why
  5. At least one maintainer approval is required before merging
  6. All CI checks must pass

Do not introduce hardcoded credentials, internal URLs, client-specific identifiers, or PII. Ensure any new dependency has a GPL-2.0-or-later-compatible license (MIT, BSD, Apache-2.0, ISC, and similar permissive licenses are all compatible).

License

By contributing you agree that your contributions are licensed under the GNU General Public License v2.0 or later.

Security

Please do not report security vulnerabilities through public GitHub issues. See SECURITY.md for the responsible disclosure process.