Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
180 lines (134 loc) · 6.77 KB

CONTRIBUTING.md

File metadata and controls

180 lines (134 loc) · 6.77 KB

Contributing to Workflow Metrics

Thank you for your interest in contributing. Please read this guide before opening a pull request.

How to contribute

  1. Fork the repository by clicking the "Fork" button on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/<your-username>/workflow-metrics.git
cd workflow-metrics
  3. Create a branch for your change: 
    git checkout -b feat/my-feature
# or
git checkout -b fix/my-bug
  4. Install dependencies and set up the project (see Setup below).
  5. Make your changes, following the coding standards.
  6. Test your changes locally (see Test below).
  7. Commit using Conventional Commits: 
    git commit -m "feat: add DORA metrics export to CSV"
git commit -m "fix: resolve crash when repository has no workflow runs"
  8. Push your branch to your fork: 
    git push origin feat/my-feature
  9. Open a Pull Request against the main branch of this repository. Fill in the PR template that appears automatically.

The CI pipeline will run lint, tests, and a build check on your PR. All checks must pass before the PR can be merged.

Coding standards

  • Use Conventional Commits for commit messages — this drives automated versioning and changelog generation.
  • Write strict TypeScript; avoid any.
  • Keep server-side logic (GitHub API, Supabase, AI calls) in src/lib/server/. Keep UI logic in src/lib/components/ and route files. Do not mix them.
  • Add or update tests for any logic change in src/lib/server/ or src/lib/utils.ts.
  • Maintain coverage thresholds: lines/functions/statements ≥ 80%, branches ≥ 70%.
  • Update README.md if your change adds a feature or modifies existing behaviour.

Prerequisites

  • Node.js >= 24
  • PNPM >= 10
  • A Supabase project (for auth and database)
  • A GitHub OAuth App (for GitHub login)

Setup

pnpm install

Copy the example environment file and fill in your credentials:

cp .env.example .env

Required environment variables:

Variable Description
PUBLIC_SUPABASE_URL Your Supabase project URL
PUBLIC_SUPABASE_ANON_KEY Your Supabase anon key
GITHUB_APP_ID GitHub App ID (for server-side API calls)
GITHUB_APP_PRIVATE_KEY GitHub App private key
MISTRAL_API_KEY Mistral API key (for AI optimization features)

Development

pnpm dev

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

Build

pnpm build

Test

pnpm test
pnpm lint
pnpm check

To run tests with coverage:

pnpm test:coverage

Coverage is enforced at: lines/functions/statements ≥ 80%, branches ≥ 70%.

CI (Pull request checks)

On every pull request to main, GitHub Actions runs:

  • Lint: ESLint (TypeScript + Svelte)
  • Test: Vitest with v8 coverage, uploaded to Codecov
  • Build: SvelteKit build check
  • Security: pnpm audit --audit-level=high (fails on high or critical vulnerabilities)
  • Dependency Review: Scans dependency manifest changes for known vulnerabilities

Workflow file: .github/workflows/pull-request.yml.

Security (Harden Runner)

All GitHub Actions workflows use step-security/harden-runner with egress blocking to mitigate supply chain attacks. Only explicitly allowed endpoints can be reached.

What it does:

  • Monitors network egress to detect unauthorized outbound calls
  • Tracks file integrity to detect tampering
  • Monitors process activity for suspicious behavior

Workflows protected:

Audit results and insights are available at the Step Security dashboard.

Release & Publishing

Automated Release

Releases are automated with Semantic Release. On every push to main:

  1. Test job runs: lint, unit tests (Vitest), and build.
  2. Release job runs only if tests pass: Semantic Release analyzes commits, bumps the version, updates package.json and CHANGELOG.md, pushes a release commit, and creates a GitHub release.
  3. Deploy job runs if a new release was created: builds and deploys to Cloudflare Pages.

Use Conventional Commits so versions and changelog are derived from commit messages:

  • feat: ... → minor release (e.g. 1.1.0)
  • fix: ... → patch (e.g. 1.0.1)
  • feat!: ... or fix!: ... → major (e.g. 2.0.0)
  • docs:, chore:, etc. → no release (included in changelog when relevant)

Workflow: .github/workflows/release.yml.

Deployment

Deployment to Cloudflare Pages is triggered automatically after a successful release. The build adapter is @sveltejs/adapter-cloudflare.

Required Secrets (in GitHub repository settings):

Secret Description
CLOUDFLARE_API_TOKEN Cloudflare API token with Pages deploy permissions
CLOUDFLARE_ACCOUNT_ID Cloudflare account ID
SUPABASE_URL Supabase project URL (production)
SUPABASE_ANON_KEY Supabase anon key (production)
GITHUB_APP_ID GitHub App ID (production)
GITHUB_APP_PRIVATE_KEY GitHub App private key (production)
MISTRAL_API_KEY Mistral API key (production)

Stack