Contributing Guide

​

Project Status

1. Testing the CLI and web app in real workflows
2. Opening issues for bugs, edge cases, or missing features
3. Improving documentation — clarity, examples, diagrams
4. Contributing security analysis rules for the audit system

​

Getting Started

​

Prerequisites

• Node.js 24 or later
• pnpm 10 or later (install via corepack enable)
• Python 3.14 or later (for security analysis)
• A Supabase project (for database)
• A GitHub OAuth App (for authentication)

​

Development Setup

git clone https://github.com/tankpkg/tank.git
cd tank

corepack enable
pnpm install

cp .env.example .env.local

cd apps/web
npx drizzle-kit push

pnpm dev --filter=web

pnpm test              # All tests (461 TypeScript + 16 Python)
pnpm test --filter=cli # CLI tests only
pnpm test --filter=web # Web tests only

​

How to Contribute

​

Report a Bug

• Expected behavior — What you thought would happen
• Actual behavior — What actually happened
• Steps to reproduce — How to trigger the bug
• Environment — OS, Node version, Tank version

​

Suggest a Feature

• Check existing issues to avoid duplicates
• Consider if it fits Tank’s core mission (security-first package management)

​

Submit Code

git checkout -b feat/my-feature

git push origin feat/my-feature

​

Pull Request Guidelines

​

Before Submitting

• Keep PRs focused — One logical change per PR
• Update documentation if your change affects user-facing behavior
• Add tests for new functionality
• Ensure all checks pass before requesting review
• Follow existing patterns — Look at similar files for consistency

​

PR Description Template

## Summary
Brief description of what this PR does.

## Changes
- Bullet list of specific changes
- Include file paths when relevant

## Testing
How did you test this? What commands did you run?

## Related Issues
Fixes #123

​

Review Process

1. Automated checks run (tests, linting)
2. Maintainer reviews code
3. Address feedback with new commits
4. Once approved, maintainer merges

​

Commit Messages

feat: add permission budget validation
fix: resolve lockfile hash mismatch on Windows
docs: clarify semver enforcement rules
chore: update CI workflow
test: add integration tests for install command
refactor: extract version resolution logic

​

Types

• feat — New feature
• fix — Bug fix
• docs — Documentation
• chore — Tooling, dependencies, config
• test — Tests
• refactor — Code refactoring (no behavior change)
• perf — Performance improvement
• ci — CI/CD changes
• style — Formatting (no code change)

​

Format

type(scope): subject

[optional body]

[optional footer]

# Simple
feat: add OIDC SSO support

# With scope
fix(cli): handle permission escalation on update

# With body
refactor(web): extract storage provider interface

Creates an abstraction layer for storage backends,
allowing on-prem deployments to use local filesystems
instead of Supabase Storage.

# With breaking change
feat!: require Node.js 24+

BREAKING CHANGE: Drop support for Node.js <24

​

Coding Standards

​

TypeScript/JavaScript

• Strict TypeScript — No any, no @ts-ignore, no as any
• TDD — Write failing tests first (RED → GREEN → REFACTOR)
• ESM only — "type": "module", no require()
• 2-space indent, LF line endings — Enforced via .editorconfig
• Import paths — Web app uses @/* alias, CLI uses relative .js extensions
• Test files — __tests__/*.test.ts (never .spec.ts)

​

Web App

• Server Components by default — 'use client' only when needed
• Tailwind CSS v4 via @tailwindcss/postcss
• Zod for validation — Never trust raw input
• Drizzle ORM — Never raw SQL or Prisma
• react-doctor — React linting (60+ rules)

​

Python

• Pydantic 2 for all models — Strict validation
• pytest for testing — test_*.py pattern
• Type hints on all functions

​

Anti-Patterns

​

Project Structure

tank/
├── apps/
│   ├── cli/              # Tank CLI — Commander.js, 16 commands
│   │   ├── bin/tank.ts   # Entry point
│   │   └── src/
│   │       ├── commands/ # 1-file-per-command pattern
│   │       └── lib/      # API client, config, lockfile, packer
│   └── web/              # Next.js 15 registry + API
│       ├── app/          # App Router: (auth), (dashboard), (registry), api/
│       ├── lib/          # DB, auth, storage, email, audit
│       └── api-python/   # Python security scanner stubs
├── packages/
│   └── shared/           # Zod schemas, types, constants
├── python-api/           # FastAPI security scanner
│   └── lib/scan/         # 6-stage pipeline
├── e2e/                  # End-to-end tests
└── docs/                 # Product brief, architecture, roadmap

​

Where to Look

​

Testing

​

Running Tests

# All tests
pnpm test

# Specific workspace
pnpm test --filter=cli
pnpm test --filter=web
pnpm test --filter=shared

# E2E tests (needs .env.local)
pnpm test:e2e

# Performance tests (needs real DB)
pnpm test:perf

​

Writing Tests

import { describe, it, expect } from 'vitest';

describe('feature', () => {
  it('should do something', () => {
    expect(true).toBe(true);
  });
});

def test_feature():
    assert True

​

Test Guidelines

• TDD — Write test first (RED → GREEN → REFACTOR)
• Descriptive names — should validate permissions not test1
• One assertion per test when possible
• Arrange, Act, Assert pattern
• No side effects — Tests should be independent

​

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Assume good intent
• Report unacceptable behavior to [email protected]

​

License

​

Questions?

​

Next Steps