Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
297 lines (205 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

297 lines (205 loc) · 11.6 KB
Raw

Contributing to sanity-plugin-seofields

Thanks for taking the time to contribute! Whether you're fixing a bug, improving docs, suggesting a feature, or reporting an issue — every contribution helps make the plugin better for the whole Sanity community.

Table of contents

Code of conduct

This project follows the Contributor Covenant Code of Conduct. By participating you agree to uphold it. Please report unacceptable behaviour to hello@thehardik.in.

Ways to contribute

You don't have to write code to contribute:

What How
🐛 Report a bug Open a bug report
💡 Suggest a feature Open a feature request
📖 Improve docs Edit a doc page and open a PR
✅ Fix a bug Comment on the issue, fork, and open a PR
⭐ Spread the word Star the repo, leave a review, or share it with your team

Reporting bugs

Before opening a new issue, please search existing issues to avoid duplicates.

When you open a bug report, include:

  • Plugin version — run npm list sanity-plugin-seofields to find it
  • Sanity Studio version — v3, v4, or v5
  • Node.js version — run node -v
  • Steps to reproduce — a minimal example is ideal
  • Expected behaviour — what you expected to happen
  • Actual behaviour — what actually happened
  • Screenshots or error output — if relevant

Security vulnerabilities — please do not open a public issue. Email hello@thehardik.in directly. See SECURITY.md for the full policy.

Suggesting features

Open a feature request issue and describe:

  • The problem you're trying to solve
  • Your proposed solution
  • Any alternatives you've considered
  • Whether you'd be willing to implement it yourself

Feature requests are discussed openly. If you want to start building before a decision is made, comment on the issue first so work isn't duplicated.

Your first pull request

Never opened a PR on an open-source project before? No worries. Here's a quick primer:

  1. Look for issues labelled good first issue — these are intentionally small and well-scoped.
  2. Comment on the issue saying you'd like to tackle it. The maintainer will assign it to you.
  3. Fork the repo, make your change, and open a PR. The Development setup section below walks you through it.

Development setup

Prerequisites

Tool Minimum version
Node.js 18.x
npm 9.x
Sanity Studio v3, v4, or v5

Fork and clone

# 1. Fork the repo on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/sanity-plugin-seofields.git
cd sanity-plugin-seofields

# 2. Add the upstream remote so you can pull in future changes
git remote add upstream https://github.com/hardik-143/sanity-plugin-seofields.git

Install dependencies

npm install

Link the plugin into a local Sanity Studio

The fastest way to test your changes live is to link the plugin into an existing Sanity Studio project on your machine:

# In the plugin root — build and watch for changes
npm run watch

# In your Sanity Studio project — link the local build
npm link /path/to/sanity-plugin-seofields

Then start Sanity Studio normally (npm run dev / sanity dev) and the studio will pick up your local build. Any file change in the plugin that triggers a rebuild will hot-reload in the studio.

Useful scripts

Command What it does
npm run watch Build in watch mode
npm run build Production build (ESM + CJS + CLI via tsup)
npm run lint Run ESLint
npm run typecheck Run tsc --noEmit type check
npm run format Run Prettier
npm test Run the Jest test suite

Project structure

sanity-plugin-seofields/
├── src/
│   ├── components/        # React field inputs, SERP preview, health dashboard
│   ├── schemas/types/     # Base SEO Sanity types (seoFields, openGraph, twitter, robots, metaTag, metaAttribute)
│   ├── schema/            # Schema.org system — 38 types + JSON-LD components
│   ├── cli/               # CLI commands (init, doctor, report, export)
│   ├── helpers/           # buildSeoMeta() and other frontend helpers
│   ├── utils/             # Shared utilities
│   ├── index.ts           # Studio plugin entry (plugins: [seofields()])
│   ├── plugin.ts          # definePlugin implementation
│   ├── next.ts            # Next.js / React export entry
│   ├── define-cli.ts      # CLI config helper entry
│   └── types.ts           # Shared TypeScript types
├── CHANGELOG.md           # Keep a Changelog format, updated with every release
├── CONTRIBUTING.md        # This file
├── package.json
├── tsup.config.ts         # Build entry points and externals
└── tsconfig.json

Adding a new Schema.org type

Each Schema.org type lives in its own subdirectory under src/schema/ (e.g. src/schema/article/) as a set of files:

  • schema.ts — Sanity schema definition with the correct fields and validation
  • component.tsx — React component that renders the <script type="application/ld+json"> tag, plus its buildXxxJsonLd() helper
  • types.ts — TypeScript types for the schema data
  • index.ts — barrel export for the type

Follow the pattern of an existing type (e.g. article) as your template. The type must be added to the barrel exports in src/schema/index.ts (Sanity plugin) and src/schema/next.ts (React component), and to the schemaOrg() combined helper.

Making changes

Always branch from main

git checkout main
git pull upstream main
git checkout -b fix/your-fix-name   # or feat/your-feature-name

Branch naming conventions:

Prefix Use for
fix/ Bug fixes
feat/ New features
docs/ Documentation only
chore/ Build, config, dependency updates
refactor/ Code restructuring with no behaviour change

TypeScript

  • All new code must be written in TypeScript.
  • Export any new public-facing types from the appropriate types/ file.
  • Run npm run typecheck before committing — PRs with TypeScript errors will not be merged.

Code style

  • ESLint and Prettier are configured. Run npm run lint and npm run format before committing.
  • Don't disable lint rules with // eslint-disable unless there is no alternative — explain why in a comment if you do.

Sanity schema compatibility

  • All schema changes must work in Sanity Studio v3, v4, and v5.
  • Do not use any Sanity API that is marked deprecated in v3.
  • Test your changes against at least one Studio version before submitting a PR.

Commit messages

This project follows Conventional Commits:

<type>(<scope>): <short description>

[optional body]

[optional footer — e.g. Closes #12]

Types:

Type When to use
feat A new feature
fix A bug fix
docs Documentation only
refactor Code change that neither fixes a bug nor adds a feature
chore Build process, dependency, or config changes
test Adding or updating tests

Examples:

feat(schema): add MedicalCondition type

fix(dashboard): correct popover position inside desk panes

Closes #8

docs(readme): update v5 compatibility note

Commits that do not follow this format may be squashed and reworded by the maintainer when merging.

Submitting a pull request

  1. Make sure npm run lint and npm run typecheck both pass locally.
  2. Push your branch to your fork.
  3. Open a PR against hardik-143/sanity-plugin-seofields on the main branch.
  4. Fill in the PR template — describe what changed, why, and how to test it.
  5. Link any related issues with Closes #<issue-number> in the PR body.

What to expect:

  • PRs are reviewed within a few days. Complex changes may take longer.
  • The maintainer may request changes — please respond to review comments or let us know if you need help.
  • Once approved, the maintainer will squash-merge the PR into main.
  • Your contribution will appear in the next CHANGELOG.md entry and release.

PR checklist

Before marking your PR as ready for review, confirm:

  • npm run lint passes
  • npm run typecheck passes
  • Changes tested against Sanity Studio locally
  • New public APIs are exported from the correct entry point
  • Docs updated if behaviour changed (or a docs follow-up issue opened)
  • Commit messages follow the Conventional Commits format

Changelog

This project uses Keep a Changelog format and Semantic Versioning.

You do not need to update CHANGELOG.md in your PR — the maintainer handles this before each release. However, if your change is significant (new feature, breaking change, or important fix), briefly describe it in your PR description so it's easy to write up accurately.

License

By contributing to sanity-plugin-seofields, you agree that your contributions will be licensed under the MIT License that covers this project.

Questions? Open a GitHub Discussion or reach out via the docs site.