.git/hooks/pre-commit (simplified bash wrapper for demonstration)

// project-scanner.ts
import { Octokit } from "octokit";

const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

export async function evaluateRepo(owner: string, repo: string) {
  const [repoData, issues, prs] = await Promise.all([
    octokit.rest.repos.get({ owner, repo }),
    octokit.rest.issues.listForRepo({ owner, repo, state: "open", labels: "good first issue" }),
    octokit.rest.pulls.list({ owner, repo, state: "open" })
  ]);

  const isHealthy = 
    repoData.data.updated_at > new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString() &&
    repoData.data.license?.key !== null &&
    issues.data.length > 0;

  const mergeVelocity = prs.data.filter(pr => pr.merged_at).length / Math.max(prs.data.length, 1);

  return {
    name: repoData.data.full_name,
    healthy: isHealthy,
    mergeVelocity: mergeVelocity.toFixed(2),
    recommended: isHealthy && mergeVelocity > 0.4
  };
}

# .git/hooks/pre-commit (simplified bash wrapper for demonstration)
#!/bin/sh
echo "Verifying upstream sync..."
git fetch upstream
if ! git diff --quiet upstream/main; then
  echo "⚠️  Fork is behind upstream. Run: git rebase upstream/main"
  exit 1
fi

Pipeline Before opening a PR, validate that the contribution meets project standards. This eliminates 80% of initial review comments.

// pr-validator.ts
import { execSync } from "child_process";
import fs from "fs";

export function validatePRReadiness(repoPath: string): { valid: boolean; errors: string[] } {
  const errors: string[] = [];

  // Check for linked issue in PR template or commit message
  const commits = execSync("git log --oneline -1", { cwd: repoPath }).toString().trim();
  if (!/#\d+/.test(commits)) {
    errors.push("Missing linked issue reference in commit message");
  }

  // Verify linting and type checking pass
  try {
    execSync("npm run lint && npm run typecheck", { cwd: repoPath, stdio: "pipe" });
  } catch {
    errors.push("Linting or type checking failed");
  }

  // Ensure PR template exists
  if (!fs.existsSync(`${repoPath}/.github/PULL_REQUEST_TEMPLATE.md`)) {
    errors.push("Repository lacks PR template; verify contribution guidelines");
  }

  return { valid: errors.length === 0, errors };
}

Architecture decision: Shift validation left. Running lint, type checks, and issue-linking verification locally prevents CI waste and signals professionalism to maintainers. The pipeline is framework-agnostic but defaults to TypeScript tooling (tsc, eslint) for consistency.

Step 4: Review Negotiation & Iteration Protocol

Maintainer feedback is rarely personal; it is structural. Treat review cycles as state transitions.

1. Acknowledge feedback within 24 hours.
2. Apply changes in isolated commits; avoid force-pushing over merged history.
3. Request clarification only after attempting implementation.
4. Use git commit --amend only when the PR is still open and CI is green.
5. Document architectural trade-offs in the PR description, not in comments.

Step 5: Contribution Ledger & Branding Integration

Track merges, recognition, and ecosystem impact. This transforms contributions into verifiable career assets.

// contribution-ledger.ts
export interface ContributionRecord {
  repo: string;
  prNumber: number;
  mergedAt: string;
  type: "bugfix" | "feature" | "docs" | "refactor";
  maintainerRecognition?: string;
}

export class ContributionLedger {
  private records: ContributionRecord[] = [];

  add(record: ContributionRecord) {
    this.records.push(record);
    this.persist();
  }

  getSummary() {
    return {
      totalMerges: this.records.length,
      byType: this.records.reduce((acc, r) => {
        acc[r.type] = (acc[r.type] || 0) + 1;
        return acc;
      }, {} as Record<string, number>),
      recent: this.records.slice(-5)
    };
  }

  private persist() {
    fs.writeFileSync("contributions.json", JSON.stringify(this.records, null, 2));
  }
}

Architecture decision: Local persistence avoids third-party dependencies. The ledger feeds directly into portfolio sites, technical blogs, and performance reviews. Structured metadata enables trend analysis and targeted ecosystem engagement.

Pitfall Guide

1. Contributing to Inactive or Architecturally Misaligned Projects

Submitting changes to repositories with no recent maintainer activity or conflicting technical direction guarantees rejection. Verify commit frequency, release cadence, and roadmap alignment before investing time.

Best practice: Use the evaluateRepo scanner to filter targets. Prioritize projects where your stack matches the primary language and where maintainers actively triage issues.

2. Ignoring CONTRIBUTING.md and Project Conventions

Every mature repository defines expectations: commit format, testing requirements, documentation standards, and communication channels. Bypassing these signals disregard for maintainer time.

Best practice: Automate convention checking. Integrate commitlint, prettier, and project-specific ESLint configs into your fork before writing code.

3. Over-Engineering the First PR

Large refactors, architectural overhauls, or multi-module changes overwhelm reviewers. Maintainers lack context for unsolicited structural changes.

Best practice: Start with documentation fixes, test coverage gaps, or low-risk bug fixes. Demonstrate reliability before proposing complex changes.

4. Submitting PRs Without Linked Issues

Untracked changes lack context. Maintainers cannot validate scope, priority, or alignment with release planning.

Best practice: Always open or reference an issue. If one doesn't exist, create it with a clear problem statement, reproduction steps, and proposed solution before coding.

5. Neglecting Fork CI Configuration

Forks often lack the original repository's CI secrets, environment variables, or workflow permissions. This causes silent failures and delays.

Best practice: Mirror essential workflows in your fork. Use secrets fallbacks, disable production-only jobs, and verify CI passes locally via act or GitHub CLI before pushing.

6. Treating Review Feedback as Personal Criticism

Code review is a technical negotiation, not a performance evaluation. Defensive responses slow resolution and damage reputation.

Best practice: Separate ego from implementation. Acknowledge feedback, apply changes iteratively, and document decisions. If you disagree, provide benchmarks or references, not opinions.

7. Failing to Track Contributions for Branding

Untracked merges leave no verifiable trail. Employers and communities cannot assess impact without structured metadata.

Best practice: Maintain a contribution ledger. Export data to a portfolio, generate release notes summaries, and cite specific PRs in technical interviews or performance reviews.

Production Bundle

Action Checklist

• Repository Vetting: Run project health scan to confirm activity, license, and issue labeling before contributing.
• Fork Sync Protocol: Configure upstream remote and enforce pre-commit sync checks to prevent drift.
• Convention Enforcement: Install commitlint, project ESLint, and Prettier; verify local CI passes before PR creation.
• Issue-First Workflow: Open or reference a GitHub issue; document scope, reproduction, and proposed approach before coding.
• PR Readiness Validation: Execute lint, type checks, and issue-link verification; attach template with clear change summary.
• Review Negotiation Protocol: Acknowledge feedback within 24h; apply isolated commits; request clarification only after implementation attempts.
• Contribution Ledger Integration: Log merges with type, date, and maintainer recognition; export to portfolio and performance documentation.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Fixing a critical bug	Direct PR with linked issue, minimal scope	High priority, clear validation path	Low (fast merge, high visibility)
Adding a new feature	Issue proposal → maintainer approval → phased PR	Aligns with roadmap, prevents wasted work	Medium (requires coordination)
Documentation improvement	Direct PR following style guide	Low risk, high maintainer appreciation	Low (quick acceptance, brand goodwill)
Core architecture change	RFC issue → design discussion → incremental PRs	Prevents breaking changes, ensures consensus	High (extended timeline, requires buy-in)
Dependency upgrade	Automated PR via Renovate/Dependabot	Reduces manual overhead, maintains security	Low (automated, predictable)

Configuration Template

# .github/workflows/contribution-ci.yml
name: Contribution Pipeline
on:
  pull_request:
    branches: [main, develop]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run test -- --coverage
      - name: Verify conventional commits
        uses: wagoid/commitlint-github-action@v5
        with:
          configFile: commitlint.config.js

  pr-template-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check PR template presence
        run: |
          if [ ! -f .github/PULL_REQUEST_TEMPLATE.md ]; then
            echo "Missing PR template" && exit 1
          fi

// commitlint.config.js
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [2, "always", ["feat", "fix", "docs", "refactor", "test", "ci"]],
    "scope-enum": [2, "always", ["core", "utils", "docs", "ci", "deps"]],
    "subject-case": [2, "never", ["sentence-case", "start-case", "pascal-case", "upper-case"]]
  }
};

Quick Start Guide

1. Initialize Fork & Upstream: Clone the target repo, add upstream remote pointing to the original repository, and verify sync with git fetch upstream && git rebase upstream/main.
2. Install Pipeline Tools: Run npm init -y && npm i -D commitlint @commitlint/config-conventional eslint prettier typescript and configure commitlint.config.js and tsconfig.json to match project standards.
3. Enable Local CI: Add a pre-commit hook that runs npm run lint && npm run typecheck && npx commitlint --edit. Verify it blocks non-compliant commits.
4. Open First PR: Create an issue, link it in your commit message (fix(#42): resolve timeout race condition), push to fix/42-timeout, and open a PR using the repository's template. Confirm CI passes before requesting review.