Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
308 lines (203 loc) · 8.52 KB

CONTRIBUTING.md

File metadata and controls

308 lines (203 loc) · 8.52 KB

Contributing to Archway

Thanks for your interest in contributing to Archway. This document outlines the process for contributing to this project and what to expect along the way.

Archway is early-stage software. There is a lot of room to make meaningful contributions across the entire codebase — from the component library and rule engine to code generation, documentation, and the canvas UX.

Table of Contents

Getting Started

  1. Fork the repository on GitHub.
  2. Clone your fork locally:
git clone https://github.com/devsethi3/archway.git
cd archway
  1. Add the upstream remote:
git remote add upstream https://github.com/devsethi3/archway.git
  1. Create a branch for your work:
git checkout -b feature/your-feature-name

Development Setup

Prerequisites

  • Node.js 18+
  • npm or pnpm
  • PostgreSQL (local or hosted)
  • OpenRouter API key (optional, only needed for AI features)

Install dependencies

npm install

Set up environment variables

cp .env.example .env.local

Fill in your database URL, auth secret, and optionally your OpenRouter API key. Refer to the README for details on each variable.

Set up the database

npm run db:push
npm run db:seed   # optional

Start the dev server

npm run dev

The app will be available at http://localhost:3000.

Useful commands

Command Description
npm run dev Start development server
npm run build Production build
npm run lint Run ESLint
npm run db:push Push Prisma schema to database
npm run db:studio Open Prisma Studio
npm run db:seed Seed the database
npm run db:generate Regenerate Prisma client

How to Contribute

Small changes

For typo fixes, documentation improvements, or minor bug fixes, feel free to open a pull request directly.

Larger changes

For new features, significant refactors, or architectural changes:

  1. Open an issue first. Describe what you want to build and why. This lets us discuss the approach before you invest time writing code.
  2. Wait for a maintainer to respond and confirm the direction.
  3. Then proceed with implementation.

This avoids wasted effort and ensures your contribution aligns with the project's direction.

Pull Request Process

  1. Make sure your branch is up to date with main:
git fetch upstream
git rebase upstream/main
  1. Run linting and make sure there are no errors:
npm run lint

  1. Test your changes manually. If you're adding a rule engine rule or a component, verify it works on the canvas.

  2. Write a clear PR description:

    • What does this PR do?
    • Why is this change needed?
    • How did you test it?
    • Screenshots if applicable (especially for UI changes).

  3. Keep PRs focused. One feature or fix per PR. If you find an unrelated issue while working, open a separate PR for it.

  4. A maintainer will review your PR. Expect feedback — it's not personal, it's how we keep the codebase consistent.

  5. Once approved, a maintainer will merge your PR.

Coding Standards

General

  • TypeScript — strict mode is enabled. No any unless absolutely necessary, and if so, leave a comment explaining why.
  • Functional components — use hooks, not class components.
  • Small files — if a file is getting long, split it. A component file should ideally do one thing.
  • Named exports — prefer named exports over default exports (except for Next.js pages/layouts where required).

Styling

  • Use Tailwind CSS for all styling.
  • Use cn() (clsx + tailwind-merge) for conditional class names.
  • Use class-variance-authority for component variants.
  • Do not write raw CSS unless there is no Tailwind equivalent.

State management

  • Zustand for client-side global state.
  • React Query for server state and data fetching.
  • Keep component-local state in useState when it doesn't need to be shared.
  • Use Immer middleware with Zustand for complex state updates.

Validation

  • Zod for all runtime validation — API inputs, form data, environment variables.
  • Define schemas in a central location and reuse them.

Database

  • All schema changes go through Prisma. Edit prisma/schema.prisma and run npm run db:push.
  • Never write raw SQL unless Prisma cannot express the query.

AI integration

  • All AI calls go through the OpenRouter provider via the Vercel AI SDK.
  • Keep prompts in dedicated files, not inline in route handlers.
  • Always handle the case where the AI key is not configured — the app should degrade gracefully.

Commit Messages

We follow the Conventional Commits specification.

Format

type(scope): short description

Optional longer description explaining what and why.

Types

Type When to use
feat A new feature
fix A bug fix
docs Documentation changes
style Code style changes (formatting, no logic change)
refactor Code restructuring (no feature or fix)
perf Performance improvement
test Adding or updating tests
chore Tooling, dependencies, build config

Examples

feat(canvas): add drag-and-drop for Redis component
fix(analysis): correct false positive on rate limiter check
docs: update setup instructions for PostgreSQL
refactor(store): migrate canvas state to Zustand slices
chore: bump next to 16.1.6

Reporting Bugs

Open a GitHub Issue with the following:

  • Title: Clear, concise summary of the bug.
  • Environment: OS, browser, Node.js version.
  • Steps to reproduce: Exact steps to trigger the bug.
  • Expected behavior: What you expected to happen.
  • Actual behavior: What actually happened.
  • Screenshots / logs: If applicable.

Label the issue with bug.

Requesting Features

Open a GitHub Issue with:

  • Title: Short description of the feature.
  • Problem: What problem does this solve? Why do you need it?
  • Proposed solution: How you think it should work.
  • Alternatives considered: Other approaches you thought about.

Label the issue with enhancement.

We cannot build everything, but good feature requests with clear rationale are taken seriously.

Where to Help

If you're looking for a place to start, these areas have the most impact:

Component Library (lib/components/)

Add new smart components with accurate metadata. Each component should define:

  • Display name, category, and description
  • Default ports (inputs/outputs)
  • Common connection targets
  • Known scaling considerations
  • Security notes

Rule Engine (lib/analysis/rules/)

Write new analysis rules. Good rules are:

  • Specific and actionable (not vague warnings)
  • Based on real-world architecture mistakes
  • Well-documented with examples of when they trigger

Code Generation (lib/codegen/)

Improve templates or add support for new frameworks and deployment targets.

Documentation

  • Improve the README
  • Add inline code comments where logic is non-obvious
  • Write guides for common use cases

Bug Fixes

Check the issues page for bugs labeled good first issue.

Community

  • Be respectful. Read the Code of Conduct.
  • Ask questions in GitHub Discussions or Issues.
  • Don't hesitate to ask for help in a PR — we'd rather help you finish than have a stale PR.

Thanks for contributing. Every improvement matters, whether it's fixing a typo or building a major feature.