Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
275 lines (189 loc) · 6.71 KB

CONTRIBUTING.md

File metadata and controls

275 lines (189 loc) · 6.71 KB

Contributing to incident.io GitHub Action

Thank you for your interest in contributing! This document provides guidelines and prerequisites for working on this project.

Prerequisites

Getting Started

1. Clone and Setup

# Clone the repository
git clone https://github.com/incident-io/github-action.git
cd github-action

# Install dependencies
npm install

# Verify everything works
npm run all

The npm run all command runs the full validation pipeline:

  • Code formatting
  • Linting (TypeScript, Markdown)
  • Type checking
  • Tests (109 unit tests)
  • Coverage report
  • Build

2. Development Workflow

# Run tests in watch mode
npm run test:watch

# Format code
npm run format:write

# Lint code
npm run lint

# Type check
npm run typecheck

# Build for distribution
npm run package

# Run everything (before committing)
npm run all

3. Understanding the Codebase

Read these files to understand the architecture:

Key architectural points:

  • Entry point: src/index.ts → src/main.ts
  • Handler pattern: Event handlers in src/handlers.ts with CustomHandler must be last
  • ES modules: All imports must use .js extensions (TypeScript quirk)
  • Test framework: Vitest (not Jest)
  • Committed dist: The dist/ directory is committed (GitHub Actions requirement)

Making Changes

Code Style

We use automated formatting and linting:

  • Prettier for code formatting
  • ESLint for code quality
  • markdownlint for Markdown files
  • gitleaks for secrets detection

Run npm run all before committing to ensure everything passes.

Writing Tests

  • Unit tests: Add to __tests__/ with .test.ts extension
  • Use Vitest: Import from vitest, not jest
  • Mock APIs: See tests/incident-client.test.ts for examples
  • Run tests: npm test or npm run test:watch

Example test structure:

import { describe, it, expect, vi } from "vitest";

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

Building for Distribution

Critical: After changing src/, you must rebuild and commit dist/:

npm run bundle
git add src/ dist/
git commit -m "Your change description"

Why? GitHub Actions run the pre-built dist/index.js, not the source files.

Integration Testing

Integration tests require a real incident.io API key:

# Set environment variable
export INCIDENT_TEST_API_KEY="your-test-api-key"

# Run integration tests
npm run test:integration

See INTEGRATION_TESTS.md for details.

Git Workflow

Branching Strategy

  • main - Production-ready code
  • feature/* - New features
  • fix/* - bugfixes
  • docs/* - Documentation updates

Commit Messages

Use clear, descriptive commit messages:

Add integration testing infrastructure

Add comprehensive integration testing setup to validate action behavior
against real incident.io API.

Changes:
- Add integration test workflow
- Add documentation
- Add npm script

Pull Requests

  1. Fork the repository (external contributors)
  2. Create a branch from main
  3. Make changes and ensure npm run all passes
  4. Commit with clear messages
  5. Push and create a pull request
  6. Respond to review feedback

PR checklist:

  • npm run all passes locally
  • Tests added/updated for changes
  • Documentation updated if needed
  • dist/ rebuilt and committed
  • No secrets committed (gitleaks passes)

Common Gotchas

See AGENTS.md for critical patterns and gotchas.

Security

Run gitleaks locally: gitleaks detect

Suppress false positives with // gitleaks:allow comments.

CI/CD

All pull requests run through CI:

  1. Linter - Code quality checks
  2. CI - Tests and type checking
  3. Check dist/ - Verifies dist/ is up to date
  4. Licensed - License compliance

Ensure all checks pass before merging.

Changelog and Release Process

Automated Changelog Generation

This project uses AI-powered changelog generation for PRs:

How it works:

  1. When your PR is ready for review, add the label ready-for-changelog
  2. A GitHub Action automatically generates a changelog entry from your PR diff
  3. The entry is committed to CHANGELOG.md under the "Unreleased" section
  4. Review the generated entry and edit if needed (directly in CHANGELOG.md)
  5. The entry will be included in the next release

Manual trigger:

  • Go to Actions → Generate Changelog Entry → Run workflow → Select your PR

Tips for better changelogs:

  • Write clear PR titles (they help the AI understand your changes)
  • Add a detailed PR description explaining the "why"
  • Use labels to help categorize (e.g., bug, enhancement, breaking-change)

Release Process (Maintainers Only)

Releases are created manually by maintainers using a GitHub Actions workflow.

For detailed release instructions, see .github/RELEASE.md.

Quick overview:

  1. All PRs with changelog entries are merged to main
  2. Maintainer triggers the Release workflow via GitHub Actions UI
  3. Workflow automatically:
    • Bumps version in package.json
    • Rebuilds dist/
    • Finalizes CHANGELOG.md
    • Creates Git tags
    • Creates GitHub Release

Version tags:

  • Specific: v0.1.0 (immutable)
  • Minor: v0.1 (moves with patches)
  • Major: v0 (moves with minor/patch)

Users can reference the action using any of these tags:

uses: incident-io/github-action@v0      # Tracks latest v0.x.x
uses: incident-io/github-action@v0.1    # Tracks latest v0.1.x
uses: incident-io/github-action@v0.1.0  # Pinned to exact version

Getting Help

Code of Conduct

Be respectful, inclusive, and constructive. We're all here to build great software together.

License

By contributing, you agree that your contributions will be licensed under the MIT License.