merge-new-sample-pr

name	merge-new-sample-pr
description	End-to-end review-and-merge workflow for a new-sample PR in pnp/sp-dev-fx-aces. Use when: "review and merge PR", "process this new sample PR", "merge PR <N> after testing", ready to take a new-sample PR all the way from build verification to merged-into-main. Orchestrates verify-new-sample-pr (build + manual test checklist) and generate-sample-metadata (assets/sample.json), then commits just that file, pushes it to the contributor's branch, merges to main matching repo convention, posts a thank-you comment crediting the contributor with a link to the community call demo request form, and cleans up — pausing for your explicit go-ahead at each consequential step (manual test result, generated metadata review, the merge itself, and the thank-you comment).
argument-hint	<PR number or URL>

Merge New Sample PR (orchestrator)

This is a thin orchestrator over two existing skills — it doesn't duplicate their logic, it sequences them and adds the git/GitHub mechanics needed to actually get a fix committed onto someone else's PR branch and merged:

1. verify-new-sample-pr — build + manual test checklist
2. generate-sample-metadata — assets/sample.json

Four hard pause points, matching how impactful/reversible each step is — never skip these or combine them without the user's explicit go-ahead:

• After build+checklist: wait for the user to confirm manual deploy/test passed
• After generating sample.json: wait for the user to approve the content
• Before merging: wait for explicit "merge it" — this is the only step that isn't easily reversible
• Before posting the thank-you comment: wait for approval of the rendered text — it's a public, PR-visible comment

Procedure

1. Confirm PR type and permissions

gh pr view <PR_NUMBER> --repo pnp/sp-dev-fx-aces --json body --jq '.body'
gh pr view <PR_NUMBER> --repo pnp/sp-dev-fx-aces --json maintainerCanModify,author,headRefName,headRepositoryOwner,state --jq '.'

If it's not a new-sample PR, stop and suggest verify-sample-pr-build instead. If maintainerCanModify is false, stop — see the maintainer-edit-a-PR guidance in repo memory before proceeding (ask the contributor, don't force anything).

2. Run verify-new-sample-pr in full

Follow that skill's procedure exactly: checkout, build, locate .sppkg, check API permissions, extract the deployment/testing checklist, flag README gaps.

STOP and wait for the user to manually deploy/test and report back ("all ok" or a problem). Do not proceed past this point without that confirmation — this is the whole point of that skill.

3. Run generate-sample-metadata on the same checked-out branch

Only if assets/sample.json is missing or needs fixing (check first — some contributors include one). Follow that skill's procedure: gather facts, derive fields, check name uniqueness, write the file.

Show the generated file to the user and wait for approval before touching git — title/description/author wording needs a human look.

4. Stage, commit, and push — only the metadata file

Local npm install/build steps often leave incidental diffs (e.g. package-lock.json version bumps) and this repo may have other unrelated uncommitted files sitting in the working tree (e.g. skill files not yet committed to main). Stage only the new/changed assets/sample.json:

git add samples/<SampleName>/assets/sample.json
git status --short   # confirm nothing else is staged
git commit -m "Add sample.json metadata for <SampleName>"

Push to the contributor's branch to update the same PR (no separate PR):

git push <fork-remote-or-full-fork-url> <PR-branch-name>

Known auth quirks in this Codespace — try in this order if push fails:

1. Authentication error: ... push access — the default Codespaces GITHUB_TOKEN is scoped only to pnp/sp-dev-fx-aces, not third-party forks. Fix: have the user run unset GITHUB_TOKEN && gh auth login (interactive, needs a personal token with repo scope) — don't attempt this yourself, it needs their browser/device-code interaction.
2. Authentication error: ... verify locks (even after #1) — this is Git LFS lock verification, unrelated to normal push permissions (repo has no LFS-tracked files). Fix: add -c lfs.https://github.com/<owner>/<repo>.git/info/lfs.locksverify=false before push on the git invocation (global option, not a push flag).
3. If the named remote was removed in an earlier cleanup, push straight to the fork's full URL instead of re-adding a named remote.

5. Expect (and don't chase) the "Sample validation" false-negative

The Sample validation PR check will likely fail after pushing — this is expected for brand-new samples using the canonical raw.githubusercontent.com/pnp/sp-dev-fx-aces/main/... thumbnail URLs, since those files don't exist on main until after merge. Confirm (once, cache the finding) that main has no branch-protection rule requiring this check:

gh api repos/pnp/sp-dev-fx-aces/branches/main/protection

If unprotected, this check failing does not block merging. Do not "fix" it by pointing thumbnails at the contributor's fork/branch instead — that's the wrong long-term URL.

6. Wait for explicit merge go-ahead, then merge matching repo convention

This repo merges via merge commit (not squash/rebase) — confirm if unsure:

git log origin/main --oneline -10   # look for "Merge pull request #NNN" pattern

Only after the user explicitly says to merge:

gh pr merge <PR_NUMBER> --repo pnp/sp-dev-fx-aces --merge

7. Post a thank-you comment on the PR

After a successful merge, thank the contributor and invite them to present the sample in a community call. Get their GitHub login from the PR (already fetched in step 1 as author), then post:

Thank you @<author> for this new sample. If you would like to present your work in a community call please fill out the form https://aka.ms/community/request/demo

gh pr comment <PR_NUMBER> --repo pnp/sp-dev-fx-aces --body "Thank you @<author> for this new sample. If you would like to present your work in a community call please fill out the form https://aka.ms/community/request/demo"

Show the exact rendered text (with the real username substituted) to the user before posting — this is a public, PR-visible comment, so confirm the target PR and wording are right before running it. Only post once per merged PR.

8. Clean up

./.github/skills/verify-new-sample-pr/scripts/cleanup-sample-build.sh <abs-path>/samples/<SampleName>
rm -rf <abs-path>/samples/<SampleName>/node_modules
git checkout -- samples/<SampleName>/package-lock.json   # discard incidental npm-install diff, if any
git checkout main && git pull origin main
git branch -D <pr-branch-name>
git status --short   # confirm only pre-existing unrelated changes remain (e.g. uncommitted skill files)

Only remove a fork remote you added yourself for this session if it's no longer needed.

Notes

• Never push, merge, or clean up without having reached the corresponding pause point above — this skill exists to make the sequence consistent, not to remove the user's checkpoints.
• If the PR touches more than one sample folder, or isn't a clean new-sample PR, stop and flag it (same as verify-new-sample-pr).
• See /memories/repo/sp-dev-fx-aces-build-verify.md for the accumulated quirks (disk space, nvm, auth, LFS, validation false-negative) this skill references.