Skip to content

Commit 55cca6c

Browse files
favoyangfavoyang
committed
docs: adopt shared agentsnippet workflow
1 parent 2ff6bbb commit 55cca6c

2 files changed

Lines changed: 144 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,53 @@ Conflict` from the publish step.
9090

9191
- Node tooling is pinned via mise in `mise.toml`.
9292
- Pipeline variables are expected by `azure-pipelines.yml`; see `README.md` for usage examples.
93+
94+
# Pull Request Delivery Workflow
95+
96+
Deliver repository changes through pull requests by default, regardless of
97+
size. Do not make changes directly in the main checkout unless the user
98+
explicitly approves an exception. Direct commits to `main` or the default
99+
branch should be limited to explicit user-approved exceptions.
100+
101+
Follow this delivery sequence:
102+
103+
1. Create a dedicated topic branch. Use a separate worktree when repository
104+
guidance requires one or when isolation is useful.
105+
2. Make the requested change and run relevant validation.
106+
3. Update plan progress when working from a saved plan.
107+
4. Run the review gate, fix valid findings, revalidate, and repeat the review
108+
until it passes.
109+
5. Close the plan when appropriate, then commit and push the reviewed change.
110+
6. Create or update the GitHub pull request with a brief summary and the
111+
validation commands that were run.
112+
7. Verify required checks and merge when there is no blocking reason.
113+
8. Monitor deployment when applicable, then clean up the worktree and branch.
114+
115+
Do not interpret short requests such as "commit", "publish the change", "ship
116+
it", "push it", or "merge it" as approval to bypass this workflow. Unless the
117+
user explicitly says to work directly on the default branch, skip the pull
118+
request workflow, or make a direct-default-branch exception, continue the
119+
normal flow on the dedicated topic branch, using a separate worktree when
120+
applicable.
121+
122+
Direct-default-branch exceptions still need a clean scope check before
123+
committing. When an exception is approved, state that the normal pull request
124+
workflow is being bypassed because of the explicit exception.
125+
126+
Before committing, run `git status --short` and verify the staged files match
127+
the requested change. Stage files by exact path when possible. Avoid broad
128+
staging commands such as `git add .` when unrelated local work exists.
129+
130+
Include screenshots in the pull request only if a change affects rendered UI,
131+
generated visual output, or external presentation.
132+
133+
## Review Gate
134+
135+
Before committing, use the installed `$branch-review-subagent-loop` skill to
136+
review the complete branch diff. Follow the skill through any required fixes,
137+
validation, and re-review. If the skill is unavailable, ask the user to install
138+
it before continuing.
139+
140+
Create, update, or merge the pull request only after the review gate passes.
141+
Merging also requires green checks unless the user explicitly accepts the
142+
remaining risk.

‎AGENTS.template.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
5+
- `azure-pipelines.yml` defines the Azure Pipelines workflow. The pipeline is split into a containerized `BuildPackage` stage that produces a tarball artifact and a later publish stage that consumes that tarball.
6+
- `findPackage.js`, `getDistTag.js`, and `createPackageArtifactMetadata.js` are the core Node scripts used by the pipeline.
7+
- `test/` contains Mocha tests (`test-*.js`) plus shared helpers in `test/utils.js`.
8+
- `repo/` is the checkout folder for target repositories; locally it serves as a fixture project folder for pipeline testing.
9+
- Root files like `package.json` and `package-lock.json` define Node tooling and dependencies.
10+
11+
## Build, Test, and Development Commands
12+
13+
- `npm test` runs the Mocha test suite (`NODE_ENV=test` via `cross-env`).
14+
- `node findPackage.js <pkg-name> <search-path> <output-file>` locates a package.json by name and writes JSON output.
15+
- `node getDistTag.js <local_version> <latest_version>` prints the dist-tag to use when publishing.
16+
- `node createPackageArtifactMetadata.js <package-folder> <tarball-path> <dist-tag> <output-file>` writes the stage handoff metadata for a packed tarball.
17+
18+
## Coding Style & Naming Conventions
19+
20+
- JavaScript uses 2-space indentation, double quotes, and semicolons (match existing files).
21+
- Prefer clear, function-based modules exported via `module.exports`.
22+
- Tests follow `test-<module>.js` naming and use Mocha + Should.
23+
- Prettier is available in devDependencies for formatting when needed.
24+
- Add JSDoc types for new or modified functions where practical.
25+
26+
## Testing Guidelines
27+
28+
- Framework: Mocha with `should` assertions.
29+
- Add tests under `test/` and keep each file focused on one module.
30+
- Run all tests with `npm test` before submitting changes.
31+
- When modifying files, run `npm run lint` and `npm run format`.
32+
- Before committing, run `npm run format:check`.
33+
- Run `npm run typecheck` when type-related changes are made (JSDoc/tsconfig).
34+
- When changing `azure-pipelines.yml`, preserve end-to-end behavior for Git submodules, Git LFS fetches, and log visibility for clone/LFS failures because OpenUPM parses those logs.
35+
- When working from a plan, after finishing any item, always state the next
36+
concrete step. Continue doing this until the plan is genuinely complete so
37+
the user does not need to ask "what's next?".
38+
39+
## Pipeline Guardrails
40+
41+
- Treat the upstream package repository as untrusted input.
42+
- Keep untrusted package lifecycle hooks inside the containerized `BuildPackage` stage only.
43+
- Do not introduce OpenUPM publish credentials into `BuildPackage`.
44+
- `PublishPackage` and `PublishE2EPackage` must publish the tarball artifact, not the source checkout.
45+
- Keep `npm publish --ignore-scripts` in the publish stage so publish-time hooks cannot execute there.
46+
- Keep the `BuildPackage` container image aligned with `mise.toml` Node major. The YAML uses one hardcoded `nodeMajorVersion` and asserts it against `mise.toml`.
47+
- Read the npm version from `mise.toml` instead of hardcoding it in multiple places.
48+
- Keep `prepare`/Husky for local development, but disable Husky during CI dependency installation in `BuildPackage`.
49+
- Use `e2eTest=true` to route a run to the Verdaccio-based e2e publish stage. Omitted or `false` means normal OpenUPM publish.
50+
51+
## Debugging Tips
52+
53+
- For GitHub-side debugging, `gh` is allowed and preferred for inspecting workflow runs, PRs, and logs when GitHub context is relevant.
54+
- For Azure pipeline debugging, prefer preserving native command output instead of wrapping failures in generic helper scripts.
55+
- Keep clone/LFS/submodule operations in explicit script steps so their stderr/stdout remains parsable in Azure logs.
56+
- If Git LFS behavior changes, check both the container image contents and the effective Git config seen inside `BuildPackage`.
57+
- If a pipeline tool version changes, verify both the YAML `nodeMajorVersion` and the `mise.toml` values.
58+
- When queueing Azure via REST API from a non-default branch of this repo, set `sourceBranch` so the run uses that branch's pipeline definition instead of the default branch.
59+
- Verdaccio e2e config lives at `test/verdaccio/config.yaml`.
60+
- Manual e2e fixture for this repo:
61+
`repoUrl=https://github.com/favoyang/com.example.nuget-consumer`
62+
`repoBranch=1.0.1`
63+
`packageName=com.example.nuget-consumer`
64+
`packageVersion=1.0.1`
65+
`e2eTest=true`
66+
- Use `npm run test:e2e:azure` to queue the documented Azure fixture from the
67+
current branch and print the relevant publish logs automatically.
68+
- Use `node scripts/runAzureFixture.js --e2e-test false` for the normal publish
69+
validation that expects `409 Conflict`.
70+
- GitHub Actions runs the Azure-backed helper in a separate `Azure E2E` job
71+
only when the `AZURE_DEVOPS_TOKEN_OPENUPM_PIPELINE` repository secret is
72+
available.
73+
- Manual normal-publish validation should use `e2eTest=false` with a package
74+
version that is already published to OpenUPM. The expected result is a `409
75+
Conflict` from the publish step.
76+
77+
## Security Notes
78+
79+
- Use `$AZURE_DEVOPS_TOKEN_OPENUPM_PIPELINE` for Azure DevOps authentication when manual debugging requires a token.
80+
- Treat `$AZURE_DEVOPS_TOKEN_OPENUPM_PIPELINE` as a secret. Never print it, echo it, paste it into commit content, or include it in conversation responses.
81+
- Do not add commands or logs that would expose registry credentials, Azure tokens, or generated auth files.
82+
83+
## Commit & Pull Request Guidelines
84+
85+
- Commit messages follow Conventional Commits (e.g., `feat:`, `fix:`, `chore:`, `docs:`) and may include scopes like `fix(ci):`.
86+
- Use a `BREAKING CHANGE:` footer when introducing incompatible changes.
87+
- PRs should describe the change, link related issues, and note test results (e.g., `npm test`).
88+
89+
## Configuration & Environment Notes
90+
91+
- Node tooling is pinned via mise in `mise.toml`.
92+
- Pipeline variables are expected by `azure-pipelines.yml`; see `README.md` for usage examples.
93+
94+
<!-- @agentsnippet "@/pull-request-delivery-workflow.md" -->

0 commit comments

Comments
 (0)