Open source sustainability

Step 1: SBOM Generation and Health Scoring

You cannot manage what you cannot measure. The first step is generating a Software Bill of Materials (SBOM) and scoring dependencies based on sustainability metrics.

Architecture Decision: Use a centralized oss-health service that periodically scans repositories, generates SBOMs via CycloneDX, and queries metadata from package registries and GitHub APIs to calculate a health score.

TypeScript Implementation: Dependency Health Analyzer

import { createCycloneDx } from '@cyclonedx/cyclonedx-npm';
import { Octokit } from '@octokit/rest';

interface DependencyHealth {
  name: string;
  version: string;
  healthScore: number; // 0-100
  riskFactors: string[];
  maintainerCount: number;
  lastCommit: string;
}

export class OssHealthAnalyzer {
  private octokit: Octokit;

  constructor(githubToken: string) {
    this.octokit = new Octokit({ auth: githubToken });
  }

  async analyzeProject(projectPath: string): Promise<DependencyHealth[]> {
    // 1. Generate SBOM
    const sbom = await createCycloneDx({ cwd: projectPath });
    const components = sbom.components || [];
    
    const results: DependencyHealth[] = [];

    for (const component of components) {
      const health = await this.evaluateComponent(component);
      results.push(health);
    }

    return results.sort((a, b) => a.healthScore - b.healthScore);
  }

  private async evaluateComponent(component: any): Promise<DependencyHealth> {
    const riskFactors: string[] = [];
    let score = 100;

    // Extract GitHub repo from purl if available
    const repoUrl = this.extractRepoUrl(component.purl);
    let maintainerCount = 0;
    let lastCommit = '';

    if (repoUrl) {
      const [owner, repo] = repoUrl.split('/').slice(-2);
      
      // Fetch contributors and recent activity
      const { data: repoData } = await this.octokit.repos.get({ owner, repo });
      maintainerCount = repoData.collaborators_count || 0;
      
      const { data: commits } = await this.octokit.repos.listCommits({ 
        owner, 
        repo, 
        per_page: 1 
      });
      lastCommit = commits[0]?.commit.author.date || '';

      // Scoring Logic
      if (maintainerCount < 2) {
        score -= 30;
        riskFactors.push('Single maintainer risk');
      }
      
      const daysSinceCommit = this.daysSince(lastCommit);
      if (daysSinceCommit > 180) {
        score -= 40;
        riskFactors.push('Abandoned project (>6 months)');
      } else if (daysSinceCommit > 90) {
        score -= 15;
        riskFactors.push('Low activity');
      }

      // Check for security advisories
      const { data: advisories } = await this.octokit.repos.listSecurityAdvisories({
        owner,
        repo,
        state: 'unreviewed'
      });
      if (advisories.length > 0) {
        score -= 20;
        riskFactors.push('Unreviewed security advisories');
      }
    } else {
      score -= 50;
      riskFactors.push('No source repository linked');
    }

    return {
      name: component.name,
      version: component.version,
      healthScore: Math.max(0, score),
      riskFactors,
      maintainerCount,
      lastCommit
    };
  }

  private extractRepoUrl(purl?: string): string | null {
    // Simplified extraction logic for demo
    if (!purl) return null;
    const match = purl.match(/github\.com\/([^/]+)\/([^/]+)/);
    return match ? `${match[1]}/${match[2]}` : null;
  }

  private daysSince(dateString: string): number {
    if (!dateString) return 999;
    const date = new Date(dateString);
    const now = new Date();
    return Math.floor((now.getTime() - date.getTime()) / (1000 * 3600 * 24));
  }
}

Step 2: Automated Contribution Pipelines

Manual contributions are insufficient at scale. Implement CI/CD pipelines that automatically generate maintenance PRs for low-risk updates, linting fixes, and dependency bumps.

Architecture Decision: Use GitHub Actions with a custom bot service to triage issues and generate PRs. The bot should only propose changes that pass automated tests and follow project conventions.

GitHub Actions Workflow: Automated Maintenance

name: OSS Sustainability Bot
on:
  schedule:
    - cron: '0 2 * * 1' # Run weekly
  workflow_dispatch:

jobs:
  sustainability-maintenance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Health Check
        run: npm run check:oss-health
      
      - name: Generate Maintenance PRs
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.SUSTAINABILITY_BOT_TOKEN }}
          script: |
            const { execSync } = require('child_process');
            // Script analyzes SBOM and creates PRs for:
            // 1. Critical security patches
            // 2. Linting/formatting fixes
            // 3. Documentation updates
            try {
              const output = execSync('node scripts/create-maintenance-prs.js', { encoding: 'utf8' });
              core.info(output);
            } catch (error) {
              core.warning(error.message);
            }

Step 3: Maintainer-Centric PR Strategy

When human engineering is required, contributions must be optimized for maintainer bandwidth. Poorly scoped PRs increase maintainer load and damage relationships.

Technical Guidelines:

• Atomic Changes: One logical change per PR. Never bundle features and fixes.
• Test Coverage: Every PR must include tests. If the project lacks tests, add them as a prerequisite.
• Issue First: For non-trivial changes, open an issue to discuss approach before coding.
• Respect Conventions: Match the project's commit message style, coding standards, and branching model exactly.

Code Example: PR Template Enforcement

// .github/pr-template-checker.ts
// Enforces sustainability guidelines before PR creation

interface PRCheckResult {
  valid: boolean;
  errors: string[];
}

export function validateContributionPR(prBody: string, filesChanged: string[]): PRCheckResult {
  const errors: string[] = [];

  // Check for linked issue
  if (!prBody.includes('Closes #') && !prBody.includes('Fixes #')) {
    errors.push('PR must link to a related issue or provide detailed context.');
  }

  // Check for test files
  const hasTestChanges = filesChanged.some(f => 
    f.includes('.test.') || f.includes('.spec.') || f.includes('__tests__')
  );
  
  if (!hasTestChanges && filesChanged.some(f => f.endsWith('.ts') || f.endsWith('.js'))) {
    errors.push('Code changes require corresponding test updates.');
  }

  // Check scope size
  if (filesChanged.length > 15) {
    errors.push('PR scope is too large. Please split into atomic changes.');
  }

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

Architecture Rationale

• Decoupled Health Service: The health analyzer runs independently of the build pipeline to avoid slowing down CI. Results are cached and exposed via an internal dashboard.
• Bot Isolation: The sustainability bot uses a dedicated identity with scoped permissions. This prevents bot activity from polluting maintainer notifications and allows for rate-limit management.
• Feedback Loops: Contribution metrics are fed back into the health score. Projects receiving regular contributions from your organization are flagged as "Supported," reducing their risk score.

Pitfall Guide

1. The "Spray and Pray" Contribution Model

Mistake: Submitting numerous low-quality PRs (e.g., random typo fixes, automated reformatting) without understanding project priorities. Impact: Maintainers perceive this as noise. It consumes review bandwidth and damages the organization's reputation, making future critical contributions harder to merge. Best Practice: Align contributions with the project's roadmap. Focus on high-value fixes, documentation improvements, and issue triage. Quality over quantity.

2. Forking Without Upstream Strategy

Mistake: Forking a project to apply a quick fix or add a feature, then maintaining the fork indefinitely. Impact: Creates technical debt. Merging upstream changes becomes increasingly difficult as the fork diverges. Security updates must be manually ported. Best Practice: Fork only as a temporary measure. Implement a policy requiring all fork changes to be proposed upstream within 30 days. If upstream rejects, document the rationale and schedule regular rebasing.

3. Ignoring License Compliance

Mistake: Treating all open source licenses as equivalent or ignoring copyleft requirements. Impact: Legal risk. Violations can force product removal or require source code disclosure. Best Practice: Integrate license scanning into the CI pipeline. Maintain a Bill of Materials with license verification. Use tools like license-checker or FOSSA to flag violations automatically.

4. Automating Without Human Oversight

Mistake: Fully automating contribution PRs without review or context. Impact: Bots may submit changes that break project conventions, introduce regressions, or conflict with maintainer plans. This leads to PR closures and maintainer frustration. Best Practice: Use automation for detection and drafting, but require human review for submission. Implement approval gates for PRs that modify core logic or dependencies.

5. Funding the Wrong Projects

Mistake: Donating to popular projects while ignoring critical but obscure dependencies. Impact: Sustainability funding does not address the highest risks. Critical infrastructure remains under-resourced. Best Practice: Direct funding based on the health score and criticality analysis. Prioritize projects with low maintainer counts that are essential to your stack. Use Open Collective or GitHub Sponsors with targeted campaigns.

6. Treating OSS as "Done" Upon Integration

Mistake: Assuming a dependency is safe once installed. Impact: Missed security patches, version drift, and inability to leverage new features. Best Practice: Treat dependencies as active components. Schedule regular review cycles. Use Dependabot or Renovate for automated updates, but verify compatibility and test thoroughly.

7. Lack of Internal Policy

Mistake: No defined process for contributions, funding, or fork management. Impact: Inconsistent behavior across teams. Some teams may contribute aggressively while others hoard code. Risk exposure varies wildly. Best Practice: Establish an Open Source Program Office (OSPO) or clear engineering policy. Define contribution guidelines, funding budgets, and approval workflows.

Production Bundle

Action Checklist

• Audit Dependencies: Generate SBOM for all repositories and run health scoring to identify critical risks.
• Configure Health Dashboard: Deploy the oss-health service and integrate results into your internal developer portal.
• Enable Automated Updates: Configure Renovate or Dependabot with strict testing requirements for all projects.
• Establish Contribution Policy: Draft guidelines for PR scope, testing, and issue linking. Train engineering teams.
• Set Up Sustainability Bot: Deploy the maintenance bot for automated linting, docs, and minor dependency bumps.
• Allocate Funding Budget: Assign monthly budget for Open Source sustainability based on health scores and criticality.
• Review Forks: Inventory all internal forks. Create upstreaming plans or decommission unnecessary forks.
• Monitor Metrics: Track MTTR, contribution volume, and dependency drift monthly. Report to engineering leadership.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Critical vulnerability in low-maintenance lib	Fork, patch, submit upstream, fund maintainer	Immediate risk mitigation; upstreaming prevents long-term drift	Medium (Engineering + Funding)
Feature request in mature framework	Contribute code via PR; engage community	Frameworks have high standards; contribution ensures alignment	Low (Engineering only)
Abandoned utility with no alternatives	Fork, assume maintenance, hire maintainer if possible	Supply chain continuity; hiring reduces internal burden	High (Fork + Hiring)
Non-critical dependency drift	Automated update PR with test verification	Low risk; automation minimizes overhead	Negligible
License violation detected	Immediate remediation; legal review; replace if necessary	Compliance risk outweighs technical debt	High (Legal + Refactor)

Configuration Template

oss-sustainability.config.json Use this configuration to drive your sustainability automation tools.

{
  "healthThresholds": {
    "criticalScore": 60,
    "warningScore": 75,
    "maxMaintainerRisk": 1,
    "maxStaleDays": 90
  },
  "automation": {
    "enabled": true,
    "botIdentity": "oss-sustainability-bot[bot]",
    "allowedActions": ["lint-fix", "doc-update", "dep-bump-patch"],
    "requireHumanApprovalFor": ["core-logic", "new-deps", "breaking-changes"]
  },
  "funding": {
    "monthlyBudget": 5000,
    "allocationStrategy": "risk-based",
    "platforms": ["github-sponsors", "open-collective"],
    "minHealthScoreForFunding": 40
  },
  "contribution": {
    "prTemplate": ".github/pr-template.md",
    "commitConvention": "conventional-commits",
    "testRequirement": "strict",
    "issueLinking": "required"
  }
}

Quick Start Guide

1. Install CLI: Add the sustainability CLI to your tooling repository.

   npm install -g @codcompass/oss-health-cli
   

2. Run Initial Scan: Execute a comprehensive audit of your primary application.

   oss-health scan --project ./src --output sbom.json --report dashboard
   

3. Configure Policy: Copy the configuration template to your repo root and adjust thresholds based on your risk appetite.

   cp oss-sustainability.config.json .
   

4. Enable Bot: Add the GitHub Action workflow to your repository to start automated maintenance.

   mkdir -p .github/workflows
   curl -o .github/workflows/oss-sustainability.yml https://raw.githubusercontent.com/codcompass/templates/main/oss-sustainability.yml
   

5. Verify: Check the dashboard for health scores and ensure the bot has created its first maintenance PR. Review and merge to validate the pipeline.

Open source sustainability is not optional for modern engineering organizations. By implementing these technical practices, you transform open source from a liability into a resilient, collaborative asset. The investment in active stewardship pays dividends in security, stability, and engineering velocity.