Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
114 lines (86 loc) · 3.66 KB

CONTRIBUTING.md

File metadata and controls

114 lines (86 loc) · 3.66 KB

Contributing to Angular Upgrade Kit

Thank you for your interest in contributing! This plugin helps developers upgrade Angular projects using AI Agent Teams in Claude Code.

How to Contribute

Adding a New Version Reference (v22+)

When a new Angular major version is released, you can contribute a reference file:

  1. Create skills/angular-upgrade-kit/references/v{VERSION}.md
  2. Follow this template:
# v{PREV} → v{VERSION} Breaking Changes
> **Released**: {Month Year} | **Status**: ⏳ PENDING
> **Official Guide**: https://angular.dev/update-guide?v={PREV}.0-{VERSION}.0&l=1

## Environment Requirements
| Requirement | Version |
|-------------|---------|
| Node.js | {versions} |
| TypeScript | ~{version} |
| RxJS | ^{version} |
| ng-packagr | ^{version} |
| Zone.js | ~{version} |

## Before You Upgrade
{prerequisites}

## ng update Commands
\`\`\`bash
# 1. Update library peerDependencies (if monorepo)
# 2. Core + CLI
npx ng update @angular/core@{VERSION} @angular/cli@{VERSION} --allow-dirty --force
# 3. Material + CDK
npx ng update @angular/cdk@{VERSION} @angular/material@{VERSION} --allow-dirty --force
\`\`\`

## Breaking Changes
{categorized breaking changes with BEFORE/AFTER code examples}

## Verification Checklist
- [ ] `npx ng version` shows @angular/core {VERSION}.x
- [ ] Library builds
- [ ] App builds
- [ ] Tests pass
  1. Update skills/angular-upgrade-kit/SKILL.md to add the new version to the reference table
  2. Update docs/VERSION-REFERENCE.md with Node/TypeScript requirements
  3. Submit a PR with:
    • The version reference file
    • Updated SKILL.md and VERSION-REFERENCE.md
    • A note about which Angular project you tested on (name, component count, monorepo or not)

Improving Agents

Agent files are markdown with YAML frontmatter. When modifying:

  1. Never add project-specific references — all agent logic must be generic
  2. Use dynamic detection — read from package.json and angular.json, not hardcoded paths
  3. Test on a real project — describe the project in your PR

Improving Hooks

Hooks are Node.js scripts. When modifying:

  1. Use only Node.js built-in modules — no npm dependencies
  2. Test locally first: 
    echo '{"tool_input":{"command":"ng build"}}' | node hooks/pre-bash-guard.js
  3. Handle stdin gracefully — some environments don't provide /dev/stdin
  4. Cross-platform — test on macOS, Linux, and Windows

Reporting Bugs

Use the Bug Report template. Include:

  • Your Angular project version (source and target)
  • Node.js version
  • Claude Code version
  • Which agent/command/hook had the issue
  • Full error output

Feature Requests

Use the Feature Request template. Include:

  • What upgrade scenario you're trying to handle
  • Why existing agents/commands don't cover it

Development Setup

  1. Clone the repo
  2. Point Claude Code to the local plugin: 
    claude --plugin-dir ./angular-upgrade-kit
  3. Make changes to agents/commands/hooks/skills
  4. Test with /reload-plugins in a live Claude Code session

Code Style

  • Markdown: Use standard GitHub-flavored Markdown
  • JavaScript hooks: Use const/let, no var. Use require() (CommonJS). No async/await in hooks (they must be synchronous).
  • JSON: 2-space indentation

PR Requirements

  • No project-specific references outside examples/
  • All JSON files are valid (node -e "JSON.parse(require('fs').readFileSync('file.json','utf8'))")
  • All JS hooks pass syntax check (node --check hooks/*.js)
  • Tested on a real Angular project (describe in PR)
  • Updated CHANGELOG.md