Contributing Guidelines

Complete guide for contributing to the MyNATCA platform ecosystem. Covers code standards, PR process, testing requirements, and best practices.

Overview

Thank you for contributing to the MyNATCA platform! This guide will help you:

Set up your development environment
Understand our workflows and standards
Create high-quality pull requests
Navigate the code promotion process

Getting Started

1. Development Environment Setup

Follow the Local Development Setup guide to configure your environment.

Quick start:

# Clone repositories
mkdir -p ~/dev/mynatca
cd ~/dev/mynatca
git clone [platform-repo-url] platform
 
# Install dependencies
cd platform
npm install
 
# Install git hooks
./scripts/setup-git-hooks.sh
 
# Start Supabase
supabase start
 
# Seed database
./scripts/db-refresh.sh

2. Create Feature Branch

cd ~/dev/mynatca/platform
git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Code Standards

Code Style

Enforced by Prettier:

2 spaces for indentation
Single quotes for strings
Semicolons required
100 character line length
Unix line endings (LF)

Enforced by ESLint:

const preferred over let
No unused variables (except prefixed with _)
No console.log in production code (use logger)
Consistent function declarations

Run before PR:

npm run bump:patch  # Runs prettier, eslint, typescript checks

File Organization

Platform structure:

platform/
├── server.js                 # Main application
├── routes/                   # API routes
│   ├── members.js
│   ├── facilities.js
│   └── ...
├── middleware/               # Express middleware
│   ├── auth.js
│   ├── validation.js
│   └── ...
├── lib/                      # Shared utilities
│   ├── database.js
│   ├── logger.js
│   └── ...
├── scripts/                  # Automation scripts
│   ├── db-refresh.sh
│   ├── bump-version.js
│   └── ...
└── supabase/                 # Database
    ├── migrations/
    └── config.toml

Naming Conventions

Files:

kebab-case.js for JavaScript files
PascalCase.jsx for React components
snake_case.sql for migrations

Variables:

camelCase for variables and functions
PascalCase for classes and components
UPPER_SNAKE_CASE for constants
_prefixed for unused parameters

Examples:

// Good
const memberNumber = '12345';
const calculatePremiumPay = (shift) => { ... };
const MAX_RETRIES = 3;
 
function processShift(shift, _options) {  // _options unused
  // ...
}
 
// Bad
const MemberNumber = '12345';           // Should be camelCase
const calculate_premium_pay = () => {};  // Should be camelCase
const maxRetries = 3;                    // Should be UPPER_SNAKE_CASE

Comments and Documentation

JSDoc for public APIs:

/**
 * Calculate premium pay for a shift
 * @param {Object} shift - The shift object
 * @param {string} shift.type - Shift type (mid, eve, etc.)
 * @param {number} shift.hours - Hours worked
 * @returns {number} Premium pay amount
 */
function calculatePremiumPay(shift) {
  // ...
}

Inline comments for complex logic:

// Calculate CIC hours using the 2-hour minimum rule
// See PayChecker docs for business logic details
const cicHours = Math.max(calculatedHours, 2.0);

Avoid obvious comments:

// Bad
const count = 0;  // Set count to 0
 
// Good
// Reset count for new pay period calculation
const count = 0;

Git Workflow

Branch Strategy

main       ← Production
  ↑
staging    ← Pre-production testing
  ↑
feature/*  ← Your work

Branch protection:

Cannot commit directly to main or staging
All changes via Pull Requests
Pre-commit hooks enforce this

Commit Messages

Format:

type: short description (50 chars max)

Longer explanation if needed (wrap at 72 chars):
- Bullet point 1
- Bullet point 2

Refs: #issue-number

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code formatting (not visual style)
refactor: Code restructuring
test: Test additions/changes
chore: Build process, dependencies

Examples:

Good:

feat: add facility search by region

- Implement region filter in facility query
- Add region parameter to API endpoint
- Update facility list component

Refs: #123

fix: resolve date calculation error in pay periods

Pay period end dates were off by one day due to timezone
handling. Now using UTC for all date calculations.

Refs: #456

Bad:

fixed stuff

WIP

Updated code

Pull Request Process

1. Prepare Your Changes

# Ensure all tests pass
npm test
 
# Run quality checks and bump version
npm run bump:patch  # or minor/major
 
# Review changes
git diff
 
# Commit everything
git add .
git commit -m "feat: add new capability
 
- Change 1
- Change 2
 
Refs: #123"
 
# Tag (if bumped version)
git tag v1.0.1
 
# Push
git push origin feature/your-feature --tags

2. Create Pull Request

Title: Clear, descriptive (matches commit message type)

feat: add new capability

Description template:

## Summary
What does this PR do?
 
## Changes
- List of changes
- Another change
- More changes
 
## Testing
- [x] Local testing completed
- [x] Quality checks passed
- [x] Version bumped
- [ ] Tested in staging (after merge)
 
## Database Changes
- [ ] No database changes
- [ ] Migrations included (describe)
- [ ] Seed data updated
 
## Breaking Changes
- [ ] None
- [ ] Yes (describe impact and migration steps)
 
## Checklist
- [x] Code follows style guidelines
- [x] Self-reviewed code
- [x] Commented complex logic
- [x] Updated documentation
- [x] No new warnings
- [x] Tests added/updated
- [x] All tests pass
 
Refs: #123

3. Code Review

As Author:

Respond to feedback promptly
Make requested changes
Re-request review after updates
Keep PR scope focused
Don't take feedback personally

As Reviewer:

Review within 1-2 business days
Be constructive and specific
Ask questions, don't demand
Approve when ready
Test changes if needed

4. Merge and Deploy

After approval:

# Merge via GitHub (Squash and merge recommended)
# Or:
git checkout staging
git merge feature/your-feature
git push origin staging
 
# Verify in staging
curl https://staging-api.mynatca.org/api/health
 
# After staging verification, merge to main
git checkout main
git merge staging
git push origin main

Testing Requirements

Unit Tests

For new features:

// tests/calculate-premium-pay.test.js
describe('calculatePremiumPay', () => {
  test('calculates CIC pay correctly', () => {
    const shift = { type: 'mid', hours: 8 };
    expect(calculatePremiumPay(shift)).toBe(expected);
  });
 
  test('applies 2-hour minimum for CIC', () => {
    const shift = { type: 'mid', hours: 1 };
    expect(calculatePremiumPay(shift)).toBe(2.0);
  });
});

Run tests:

npm test
npm run test:watch  # Watch mode
npm run test:coverage  # Coverage report

Integration Tests

For API endpoints:

// tests/api/members.test.js
describe('GET /api/members', () => {
  test('returns member list', async () => {
    const response = await request(app)
      .get('/api/members')
      .set('Authorization', `Bearer ${token}`);
 
    expect(response.status).toBe(200);
    expect(response.body).toHaveLength(expect.any(Number));
  });
});

Manual Testing

Before creating PR:

Database Changes

Migrations

Creating migrations:

cd ~/dev/mynatca/platform  # or pay, discord
 
# Make changes in Supabase Studio
# Then generate migration:
supabase db diff -f descriptive_name
 
# Test migration
supabase db reset
 
# Commit migration
git add supabase/migrations/
git commit -m "feat: add new table for feature X"

Migration checklist:

Tested with supabase db reset
Idempotent (safe to run multiple times)
Includes indexes for foreign keys
Includes appropriate constraints
No data loss (or explicitly documented)
Backward compatible (or documented as breaking)

Schema Ownership

Rules:

Platform owns public schema
Pay owns pay schema
Discord owns discord schema
Don't modify schemas you don't own

Cross-schema references:

✅ Foreign keys from your schema to public
✅ Read from any schema
❌ Write to schemas you don't own

Documentation

When to Update Documentation

Always update docs when:

Adding new API endpoints
Changing API behavior
Adding environment variables
Changing deployment process
Adding new features
Fixing bugs that affect usage

Documentation locations:

API reference: docs/pages/technical/api/
Setup guides: docs/pages/technical/setup/
Deployment: docs/pages/technical/deployment/
Database: docs/pages/technical/database/
User guides: docs/pages/user-guides/

Documentation Standards

Use MDX format:

# Page Title
 
Brief overview paragraph.
 
## Section Heading
 
Content here.
 
### Subsection
 
More content.
 
**Code examples:**
\`\`\`bash
command example
\`\`\`
 
**Lists:**
- Item 1
- Item 2
 
**Links:**
[Link text](/technical/other-page)

Release Process

See Code Promotion Workflow for complete details.

Summary:

Feature branch → Create and develop
Quality checks → Run npm run bump:patch
Pull Request → Create to staging
Code Review → Get approval
Merge to Staging → Deploy to staging
Test in Staging → Verify everything works
Merge to Main → Deploy to production
Verify Production → Smoke tests

Common Scenarios

Adding a New API Endpoint

# 1. Create route file
cat > routes/new-feature.js << 'EOF'
const express = require('express');
const router = express.Router();
 
router.get('/new-feature', async (req, res) => {
  // Implementation
  res.json({ data: [] });
});
 
module.exports = router;
EOF
 
# 2. Register route in server.js
# Add: app.use('/api', require('./routes/new-feature'));
 
# 3. Add tests
cat > tests/api/new-feature.test.js << 'EOF'
describe('GET /api/new-feature', () => {
  test('returns data', async () => {
    // Test implementation
  });
});
EOF
 
# 4. Update API documentation
# Edit: docs/pages/technical/api/platform.mdx
 
# 5. Test locally
npm test
npm run dev
curl http://localhost:1300/api/new-feature
 
# 6. Prepare for PR
npm run bump:minor  # New feature
 
# 7. Commit and push
git add .
git commit -m "feat: add new feature endpoint"
git push origin feature/new-feature

Fixing a Bug

# 1. Create fix branch
git checkout -b fix/bug-description
 
# 2. Fix the bug
# Edit necessary files
 
# 3. Add test to prevent regression
# Edit or create test file
 
# 4. Test locally
npm test
 
# 5. Prepare for PR
npm run bump:patch  # Bug fix
 
# 6. Commit and push
git add .
git commit -m "fix: resolve bug description"
git push origin fix/bug-description

Adding Database Migration

# 1. Make schema changes in Supabase Studio
open http://127.0.0.1:54323
 
# 2. Generate migration
supabase db diff -f add_new_table
 
# 3. Review migration
cat supabase/migrations/*_add_new_table.sql
 
# 4. Test migration
supabase db reset
 
# 5. Update seed data if needed
# Edit scripts/seed.sh or pay/scripts/seed.sh
 
# 6. Prepare for PR
npm run bump:minor  # Schema change
 
# 7. Commit and push
git add supabase/migrations/
git commit -m "feat: add new table for feature X"
git push origin feature/new-table

Best Practices

DO ✅

Follow code style guidelines
Write tests for new code
Update documentation
Keep PRs focused and small
Respond to reviews promptly
Test thoroughly before pushing
Use descriptive commit messages
Run npm run bump before PRs
Keep dependencies up to date
Ask questions when unsure

DON'T ❌

Commit directly to main/staging
Skip tests
Leave commented-out code
Commit console.log statements
Skip documentation updates
Create massive PRs
Force push to shared branches
Hardcode configuration
Ignore linter warnings
Skip code review

Getting Help

Resources:

Ask for help:

Slack: #dev channel
GitHub: Comment on issues/PRs
Team: Ask teammates directly

Quick Reference

# Setup
./scripts/setup-git-hooks.sh
npm install
supabase start
./scripts/db-refresh.sh
 
# Development
git checkout -b feature/name
# ... make changes ...
npm test
npm run bump:patch
git commit -m "feat: description"
git push origin feature/name
 
# Quality checks
npm test
npm run lint
npm run format
npm run type-check
 
# Migrations
supabase db diff -f name
supabase db reset
 
# Deployment
npm run bump:patch   # Bug fixes
npm run bump:minor   # New features
npm run bump:major   # Breaking changes