Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
268 lines (179 loc) · 6.79 KB

CONTRIBUTING.md

File metadata and controls

268 lines (179 loc) · 6.79 KB

Contributing to Delegate Action

Pull requests welcome. Breaking changes less so. Read this first.

Thanks for considering contributing to delegate-action! Before you dive in, here's how we do things around here. We're not picky, but we do have standards. And those standards are enforced by robots.

Code of Conduct

Don't be a jerk. That's it. That's the whole code of conduct.

Be respectful, be constructive, and remember that open source is a collaborative effort. If you can't handle feedback on your PR, this might not be the place for you.

Getting Started

  1. Fork the repository (top-right corner, you know where it is)
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/delegate-action.git
cd delegate-action
  3. Install dependencies: 
    npm install
    This will also set up Lefthook pre-commit hooks. They're there to save you from yourself.
  4. Create a feature branch: 
    git checkout -b feat/your-amazing-feature
    Notice the feat/ prefix? That's intentional. We'll get to that.

Development Workflow

Build

npm run build

This compiles the action into dist/ using @vercel/ncc. The dist/ folder is committed to the repo because GitHub Actions requires it. Yes, we commit built artifacts. No, there's no way around it.

Lint

npm run lint

Runs ESLint with the flat config (eslint.config.mjs). Targets ECMAScript 2024 (Node.js 22 LTS). If it fails, fix it. Don't argue with the linter.

Format

npm run format       # Auto-fix
npm run format:check # Check only

Uses Prettier to enforce consistent code style. If you don't like Prettier, that's fine. But you still have to use it.

Test

npm test

Currently just a placeholder. If you're adding new functionality, add tests. If you're not adding tests, at least acknowledge that you should be.

Commit Guidelines

This project uses Conventional Commits. If you don't follow the format, the CI will reject your commit. This is not negotiable.

Format

<type>(<scope>): <subject>

Types

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, whitespace, etc.)
  • refactor: Code refactoring (no functional changes)
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Build system changes
  • ci: CI/CD changes
  • chore: Maintenance tasks (dependency updates, etc.)

Responsible AI Attribution

Every commit MUST include RAI (Responsible AI) attribution. This is enforced by @checkmarkdevtools/commitlint-plugin-rai.

Format:

<type>: <subject>

RAI: <human|AI|pair> - <explanation>

Examples:

feat: add support for custom Copilot commands

RAI: human - Implemented manually based on user feedback

fix: resolve path traversal vulnerability

RAI: pair - AI suggested fix, human reviewed and tested

docs: update README with new examples

RAI: AI - Generated by Copilot, reviewed by human

If you don't include RAI attribution, the pre-commit hook will block your commit. Don't try to skip it with --no-verify. We'll know.

Examples (Good)

feat: add retry logic for Copilot API calls

RAI: human - Designed and implemented without AI assistance

fix: prevent memory exhaustion on large files

RAI: pair - AI suggested approach, human refined implementation

docs: add AGENTS.md with CI workflow documentation

RAI: AI - Drafted by GPT-4, edited for tone and accuracy

Examples (Bad)

Added feature

❌ Missing type, scope, and RAI attribution

feat added feature

❌ Missing colon, improper format

feat: Add Feature

❌ Subject should be lowercase

Pre-commit Hooks

Lefthook runs automatically on every commit. The sequence is:

  1. Format (npm run format) - Auto-fixes code style
  2. Lint (npm run lint) - Catches code issues
  3. Test (npm test) - Runs tests

If any step fails, the commit is blocked. Fix the issue and try again.

Want to skip the hooks? (Don't.)

git commit --no-verify

But seriously, don't. The CI will catch it anyway and your PR will fail. Save yourself the embarrassment.

Pull Request Process

  1. Update documentation if your changes affect usage or behavior
  2. Ensure all tests pass (yes, even the ones you didn't write)
  3. Run linting and formatting: 
    npm run lint && npm run format
  4. Build the action: 
    npm run build
  5. Commit the built dist/ directory (yes, really)
  6. Create a pull request with a clear description:
    • What changed?
    • Why did it change?
    • How did you test it?
    • Did you break anything?
  7. Wait for code review (patiently, preferably)
  8. Address feedback (if any)
  9. Get approved and merged

Code Style

  • Use ES6+ JavaScript features (async/await, destructuring, arrow functions, etc.)
  • Follow ESLint and Prettier configurations (they're there for a reason)
  • Write clear, descriptive variable and function names (no single-letter variables unless they're loop counters)
  • Add JSDoc comments for functions (especially public APIs)
  • Keep functions small and focused (if it doesn't fit on one screen, it's too big)

Security

Security is not optional. If you're adding functionality that touches user input, file paths, or external commands, pay attention.

  • Never commit secrets or credentials (use GitHub Secrets)
  • Validate all user inputs (use sanitize-filename and validator, not regex you wrote at 2 AM)
  • Use safe file path operations (path.join, not string concatenation)
  • Follow the security guidelines in SECURITY.md

If you introduce a security vulnerability, we'll find it. CodeQL, SonarCloud, and Gitleaks all run on every PR. Don't make them angry.

Release Process

Releases are automated using Release Please:

  1. Merge PRs to main branch
  2. Release Please creates/updates a release PR
  3. Merge the release PR to trigger a new release
  4. GitHub Actions publishes the new version

You don't need to touch version numbers. Release Please handles that based on Conventional Commits. This is why we enforce commit message formatting.

Questions?

Open an issue. But check the existing issues first. If someone already asked your question, don't ask it again.

Final Notes

  • Be patient. Code review takes time.
  • Be respectful. We're all here to build better software.
  • Be persistent. If your PR gets rejected, learn from the feedback and try again.

And most importantly: Have fun. Open source should be enjoyable, not a chore.

Now go forth and submit that PR.