Skip to content

Latest commit

 

History

History
80 lines (59 loc) · 3.69 KB

AGENTS.md

File metadata and controls

80 lines (59 loc) · 3.69 KB

action-gh-release

This repository is maintained as a small, user-facing GitHub Action with a relatively wide compatibility surface. Optimize for stability, reproducibility, and clear user value over broad rewrites.

Core Rules

  • Prefer narrow behavior fixes over structural churn.
  • Reproduce current behavior on master before changing code.
  • Treat GitHub platform behavior as distinct from action behavior. If GitHub controls the outcome, prefer docs or clearer errors over brittle workarounds.
  • Do not revive stale PRs mechanically. Reuse the idea if it still has value, but reimplement on top of current master.
  • Avoid standalone refactors with no clear user-facing benefit.

Current Architecture

  • src/main.ts is the orchestration layer: parse config, validate inputs, create/update release, upload assets, finalize, set outputs.
  • src/github.ts owns release semantics: lookup, create/update/finalize, asset upload, race handling, and GitHub API interaction.
  • src/util.ts owns parsing and path normalization.
  • Keep behavior-specific logic in src/github.ts or src/util.ts; avoid growing src/main.ts with ad-hoc feature branches.

Bug-Fix Workflow

  • Reproduce the issue against current master first.
  • When available, use the companion consumer harness repo action-gh-release-test.
  • Capture exact workflow run URLs and release URLs before claiming a fix.
  • If the issue is really a docs/usage or platform-limit case, document it and close it as such instead of forcing a code change.
  • If a historical issue no longer reproduces on current master, prefer a short closeout note that asks the reporter to open a fresh issue if they still see it.

Feature Triage

  • Ship features only when there is clear user value or repeated demand.
  • Small convenience features are fine, but they should stay small.
  • Weak-demand features should not expand parsing complexity, cross-platform ambiguity, or maintenance surface.
  • For old feature PRs:
    • check whether current master already covers the behavior
    • prefer a tiny docs clarification if the behavior exists but is poorly explained
    • close stale feature PRs when the idea is obsolete, low-value, or badly shaped for the current codebase

Contract Sync

When behavior changes, keep the external contract in sync:

  • update README.md
  • update action.yml
  • update tests under __tests__/
  • regenerate dist/index.js with npm run build

Docs-only changes do not need dist/index.js regeneration.

Verification

For code changes, run:

  • npm run fmtcheck
  • npm run typecheck
  • npm run build
  • npm test

For behavior changes, also run the relevant external regression workflow(s) in action-gh-release-test against the exact ref under test.

Release and Triage Conventions

  • Keep PR labels accurate. Release notes depend on them.
    • bug fixes: bug
    • docs-only changes: documentation
    • additive features: feature or enhancement
    • dependency updates: dependencies
  • Follow RELEASE.md for version bumps, changelog updates, tagging, and release publication.
  • Prefer manual issue/PR closeouts with a short rationale over implicit assumptions.
  • Do not auto-close old PRs or issues through unrelated docs PRs.

Implementation Preferences

  • Preserve the current upload/finalize flow unless there is strong evidence it needs to change.
  • Prefer upload-time semantics over filesystem mutation.
  • Be careful with parsing changes around files, path handling, and Windows compatibility.
  • Be careful with race-condition fixes; verify both local tests and consumer-repo concurrency harnesses.
  • Do not assume a refactor is safe just because tests are green. This action’s behavior is heavily shaped by GitHub API edge cases.