Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
120 lines (91 loc) · 6.3 KB

CONTRIBUTING.md

File metadata and controls

120 lines (91 loc) · 6.3 KB

Contributing to Powernode

Thanks for considering contributing to Powernode! This document covers how to get involved — filing issues, submitting changes, and the conventions we follow.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you're expected to uphold this code. Report unacceptable behavior by opening a private GitHub Security Advisory on this repository (Settings → Security → Report a vulnerability — works for conduct issues too) or via GitHub Discussions for non-sensitive matters.

Getting Started

Setup

  1. Read CLAUDE.md — it covers the architecture, conventions, MCP-first workflow, and platform organization. The file is named for the AI assistant we use during development, but the conventions apply to all contributors.
  2. Follow setup in README.md for installing dependencies and running the platform locally.
  3. Set up extension frontend symlinks (one-time, after cd frontend && npm install): 
    ./scripts/setup-extension-frontend-symlinks.sh
    This creates extensions/<ext>/frontend/node_modules symlinks to the parent's frontend/node_modules so extension Jest tests can resolve dependencies. The symlinks are gitignored; the script is idempotent.
  4. Run the test suite to confirm your environment works: 
    cd server && bundle exec rspec --format progress
cd frontend && CI=true npm test

Repository Layout

  • server/ — Rails 8 API backend
  • frontend/ — React 19 / TypeScript frontend
  • worker/ — Standalone Sidekiq worker (HTTP-only API to server, never imports server code)
  • extensions/ — Optional feature extensions: business (billing/SaaS), marketing (campaigns/landing pages), system (fleet/edge), trading, supply-chain
  • docs/ — Architecture, feature, and platform documentation
  • scripts/ — Build, validation, and utility scripts

Filing Issues

Use the appropriate template:

  • Bug reports — for things that are broken (use the bug report template)
  • Feature requests — for proposals (new capability, integration, or workflow)
  • Security issues — DO NOT file as public issues. Open a private GitHub Security Advisory with details. We'll respond within 72 hours and coordinate disclosure.

Please search existing issues first to avoid duplicates.

Submitting Pull Requests

  1. Fork the repo and create a feature branch from develop: 
    git checkout -b feature/your-change-name develop
  2. Branch strategy: PRs target develop. The release flow is develop → release/x.y.z → master.
  3. Make focused changes: one PR = one logical change. Smaller PRs review faster and ship sooner.
  4. Follow the conventions documented in CLAUDE.md. Highlights:
    • Frontend permissions: currentUser?.permissions?.includes('name') — NEVER check roles
    • Theme classes only: bg-theme-*, text-theme-* — no hardcoded colors
    • API responses: render_success() / render_error() — never bare render
    • Ruby pragma: # frozen_string_literal: true on every .rb file
    • Frontend logging: import { logger } from '@/shared/utils/logger' — no console.log in production code
    • TypeScript: no any types — proper types required
  5. Add tests for new behavior:
    • Backend: spec/ (RSpec) — see existing patterns in spec/factories/, spec/support/
    • Frontend: *.test.tsx (Jest) — see existing component tests
    • E2E: e2e/ (Playwright) — see e2e/pages/ for page objects
  6. Run validation before pushing: 
    ./scripts/validate.sh
    Or for a quicker subset: ./scripts/validate.sh --skip-tests
  7. Commit messages: type(scope): subject — e.g., feat(marketing): add waitlist signup endpoint. See recent git log --oneline for style.
  8. No AI-assistant attribution in commit messages (no "Co-Authored-By: Claude", etc.) — keep them clean.

What We're Looking For

  • Bug fixes (especially with regression tests)
  • Documentation improvements
  • New extensions (see extensions/ for shape — system, marketing, business, trading)
  • Integration adapters: Claude Agent SDK, LangGraph, Mastra, OpenAI Agents SDK, AutoGen, Vercel AI SDK
  • Performance improvements with measurements
  • Test coverage in under-tested areas (the extensions/business/spec/ directory in particular)
  • Accessibility improvements with data-testid and ARIA labels

What We're Not Looking For (right now)

  • Cosmetic refactors without functional change
  • Style-only PRs that fight existing patterns
  • Breaking changes without prior issue discussion
  • Auto-generated content (typo-fix bots, dependency-update spam unrelated to security)
  • License changes (we're staying MIT — see LICENSE)

Development Workflow

  • Read CLAUDE.md for the full MCP-first workflow if you're using AI assistance
  • Run cd frontend && npx tsc --noEmit after TypeScript changes
  • Run cd server && bundle exec rspec spec/path/to/relevant_spec.rb for targeted backend specs
  • Never run the full RSpec suite — only changed-file specs (the suite is large and slow)
  • Use ./scripts/validate.sh as a pre-push checklist

Service Management (development)

Local services run via systemd. After installing:

sudo scripts/systemd/powernode-installer.sh install
sudo systemctl start powernode.target

Then journalctl -u powernode-backend@default -f to tail logs.

Never use manual commands (rails server, sidekiq, npm start) for production workflows — they bypass the health-check infrastructure.

Communication

License

By contributing, you agree that your contributions will be licensed under the MIT License (see LICENSE).

Thanks for being part of Powernode!