How To Contribute

Green Goods is open source and built by the Greenpill Dev Guild. Whether you're fixing a bug, adding a feature, or improving docs — here's everything you need to contribute.

---

Picking Up Your First Task

Green Goods tracks all product work — bugs, ideas, polish, scoped tasks — in Linear (the Greenpill Dev Guild workspace). GitHub is for pull requests and code review only; the issue tracker is disabled by design.

To pick up your first piece of work:

1. Say hello in Discord or Telegram — Tell a maintainer what you'd like to work on and ask for a scoped starter task. Maintainers track accepted work in Linear and will point you at something good first issue-sized.
2. Read the relevant context files — Each package has a .claude/context/*.md file explaining conventions and patterns
3. Set up your local environment — Follow the Getting Started guide

Work is not open-ended bounties. Paid implementation work is grant-dependent, must be explicitly scoped with maintainers, and should be tied to clear acceptance criteria before work begins.

Understanding the codebase

Before diving into code, familiarize yourself with these key resources:

• ONBOARDING.md — Paste into Claude Code for a guided day-one setup walkthrough
• CLAUDE.md — Project-wide rules, patterns, and commands
• AGENTS.md — How agentic tools interact with the codebase
• .claude/context/ — Package-specific documentation and conventions
• Architecture docs — System architecture for the big picture

Coding standards

• Hook boundary — ALL React hooks live in @green-goods/shared. Client and admin only have components and views.
• Barrel imports — Always import { x } from "@green-goods/shared", never deep paths.
• Address types — Use Address type (not string) for Ethereum addresses.
• Error handling — Never swallow errors. Use parseContractError() + USER_FRIENDLY_ERRORS for contract errors.
• Logging — Use logger from shared, not console.log.
• Translations — User-facing strings must be added to all three translation files (en.json, es.json, pt.json).

---

Joining The Dev Guild

The Greenpill Dev Guild is a collective of builders working on regenerative public goods. Contributing to Green Goods is the best way to join:

• Start contributing — Pick issues, submit PRs, join discussions
• Join the community — Telegram for real-time coordination
• Attend meetings — Weekly dev syncs are open to contributors
• Grow your role — Consistent contributors can become core maintainers

Funding and scoped work

Green Goods welcomes unpaid open-source contributions and clearly scoped funded work. Funding depends on active grants, sponsor commitments, or maintainer-approved budgets. If compensation is part of the discussion, confirm scope, budget, review expectations, and acceptance criteria before starting implementation.

---

Making A Pull Request

Green Goods uses a develop (staging) → main (production) flow: branch from develop and open your PR into develop. Maintainers promote develop → main for production releases. Both branches require a passing-CI pull request to merge.

Branch naming

Follow the type/description convention:

feature/hats-v2
bug/admin-fix
refactor/shared-hooks
docs/architecture-update
chore/update-dependencies

Commit messages

Use Conventional Commits with scope:

feat(contracts): add yield splitter module
fix(shared): resolve query key collision in useGardenVaults
refactor(admin): extract WorkCard into standalone component
docs(builders): update architecture diagrams
test(shared): add coverage for useWorkMutation error paths
chore(deps): bump viem to 2.46.1

Types: feat, fix, refactor, chore, docs, test, perf, ci

Scopes: contracts, indexer, shared, client, admin, agent, claude

Quality gate

Run the full validation before pushing:

bun run format:check  # Check formatting
bun run lint          # Lint workspace
bun run test          # Run all tests (CRITICAL: not `bun test`)
bun run build         # Build everything (respects dependency order)

bun test vs bun run test

bun test invokes Bun's built-in test runner, which ignores your Vitest config. Always use bun run test to run the package.json script with proper environment setup.

PR workflow

1. Create a branch from develop with the naming convention above
2. Make your changes — Keep PRs focused on a single concern
3. Run the quality gate — All four commands must pass; use bun run format if formatting needs to be fixed
4. Push and create a PR — Include a clear description of what and why
5. Address review feedback — Maintainers will review within 48 hours

Writing docs

When contributing documentation:

• One primary task per page — Keep pages focused
• Start with the first user action above the fold
• Keep sections short and scannable
• Use action verbs in headings
• End with one clear next action using the NextBestAction component
• Include source_of_truth in frontmatter with real file paths
• Use approved status labels only: Live, Live (external source), Complete, In progress, Implemented (activation pending indexing), Implemented (activation pending deployment), Planned

Available docs components:

Component	Purpose
NextBestAction	Primary CTA plus optional alternatives at page end
DecisionGuide	Intent-based branching for complex workflows
QuickAnswer	Fast in-page answers without long prose
StepFlow	Step-by-step checklists
StatusBadge	Visual status indicator

---

Next page

Next: Architecture

Understand the system architecture before contributing to any package.

Architecture

• Packages
• Testing