Open a pull request (GitHub)

Project-local skill for ScienceDiscovery.

This is the only path. Changes are proposed here and GitHub syncs to GitCode; CONTRIBUTING.md's Repositories table is the authority. That direction is the reverse of what it once was, and the GitCode side no longer has a pipeline at all, so older merge requests and any documentation describing GitCode as the place to propose are out of date.

How to call gh, and the rule that issue and pull request text is English: github. Pipeline internals — which platform runs which layer, the workflow files, run logs, failure attribution: ci. Journey design and reporting: e2e-testing.

For a change tied to an existing issue, follow the GitHub skill: try to assign it to yourself when starting, post the plan on the issue, and keep progress there. If readback does not show your login, do not retry or report it as assigned; say in the plan comment that you are working on it and ask a maintainer to assign you.

Rules

1. The layers are a gate, not a suggestion. CONTRIBUTING says run all three locally. GitHub Actions runs them too, but on a pull request that is feedback arriving twenty minutes later, not permission to skip them.
2. Push the branch to the operator's own fork, never to the upstream. Resolve the login from gh api user --jq .login; do not hard-code a person. origin is openJiuwen-ai/sciencediscovery. Do not git push origin a task branch, and do not assume origin is a personal fork. Open the pull request with --repo openJiuwen-ai/sciencediscovery --head <login>:<branch> --base main.
3. Exactly one release:* label, from the whitelist below. The release note is grouped by it.
4. Read the pull request back after creating it, and read its Actions run before saying anything about CI.
5. Say what was verified, with the actual numbers. "Tests pass" is not reviewable; "UT 382 API + 100 runner, ST smoke ok, mocked E2E 42 passed / 2 skipped / 0 failed" is.
6. This skill stops at the pull request. It does not merge, tag, or publish a release.
7. The title and the body are English. See github. Write Chinese only when the person who asked explicitly wants Chinese.

Run the layers first

bwrap --ro-bind / / --dev /dev true && echo sandbox ok      # ci:ut and ci:e2e need it
CI_RESULTS_DIR=.tmp/ci-results CI_RUNTIME_DIR=.tmp/ci-runtime pnpm ci:ut
CI_RESULTS_DIR=.tmp/ci-results CI_RUNTIME_DIR=.tmp/ci-runtime pnpm ci:st
CI_RESULTS_DIR=.tmp/ci-results CI_RUNTIME_DIR=.tmp/ci-runtime pnpm ci:e2e

Run them on the commit you will push and collect the per-layer numbers for the body: the per-package # pass / # skipped lines in the UT run.log, the ST smoke line, and the E2E discovered / passed / failed / skipped split. Each layer leaves run.log and a summary under CI_RESULTS_DIR/<layer>/; with a relative CI_RESULTS_DIR, ci:e2e writes its journey reports under .e2e/.tmp/… instead, because Playwright runs from .e2e/.

When a layer fails, attribute it before touching anything: run the same layer on unmodified main in a separate detached worktree (git worktree add --detach .worktrees/<name> <sha>). An identical failure is pre-existing — say so in the body with the step, the error and the baseline run, and leave the fix to its own pull request. A failure only on your commit is yours. Never weaken an assertion or skip a layer to get green; if a layer cannot run on this host, say which and why. Report the numbers each layer's summary.json gives — planned, executed, passed — not "tests pass".

pnpm ci:e2e is the mocked browser subset only. Changed user-observable behaviour also needs the relevant API, CLI or local-stack journey.

The two hosts are different repositories

GitHub is where changes are proposed and GitCode mirrors it, but the two have separate histories either way. Two consequences bite here:

• Never compare SHAs across hosts. The same change has a different commit id on each. Compare trees: git rev-parse <a>^{tree} on both.
• Never push a GitCode-based branch to GitHub, or the reverse. Rebase onto the host's own main first (git rebase --onto github/main <old-base>), and check the result does not contain the other host's base: git merge-base --is-ancestor <other-base> HEAD must fail.

Choose exactly one release category

Label	For
release:breaking	The user must change configuration, call sites or environment
release:feature	A new or extended user-facing capability
release:fix	Wrong behaviour in something that already existed
release:performance	Speed or resource use is the point of the change
release:docs	Documentation and usage guidance
release:dependency	A dependency update is the substance of the change
release:internal	Tests, CI, developer tooling, refactors with no external behaviour change
release:skip	Not worth a line in the release note — say why

These are mutually exclusive: the label answers "which one section of the release note does this belong under", not "which properties does this change have".

• A breaking change is release:breaking and nothing else. That it is also a feature is already in the title, and an upgrading reader needs it in one place.
• A fix that also adds tests is release:fix. The tests are how it was proved, not what it is.
• A dependency bump whose purpose is fixing a user-visible bug is release:fix; a routine update is release:dependency.
• A new product capability is release:feature even when it is delivered as a Skill; maintaining a developer-facing agent skill is release:internal.
• Never choose release:skip because the author is a bot, because the change arrived by sync, or because the diff is small. Category follows content. If there is any user impact, or the category is unclear, ask rather than silently skipping — a skipped pull request leaves no trace in the note.

The categories and their order live in .github/release.yml. An unlabelled pull request is not dropped, it lands in Other Changes — which is a backstop to read and fix, not a default to rely on.

Applying a label needs write access to the upstream repository. An outside contributor can open the pull request and cannot label it. When the label cannot be applied, put the intended category in the body, say plainly that the GitHub label is pending a maintainer, and do not report it as applied. Do not invent a category outside the whitelist, and do not touch the ci-*, priority/*, sync-managed or general classification labels — they serve other purposes and this skill has no business rewriting them.

Title and body

English. The title and every section of the body are English, including validation numbers and the E2E conclusion.

Title: <type>(<scope>): <the change and its effect>, scope optional. It becomes the release note entry, so it has to read as a sentence to somebody who has not seen the diff. update, fix bug, 修改 App.tsx and 同步代码 are not titles. A pull request paired from a GitCode merge request keeps the original meaning of its title — never flatten it to Sync from GitCode.

<One paragraph: what changes and why. Lead with the problem, not the patch.>

## <Each substantive change>
<What it does, and the reasoning a reviewer cannot reconstruct from the diff.>

## Validation
<Layer results with numbers. Name anything not covered and why.>

## E2E user journeys
<PASS / FAIL / BLOCKED; tested SHA; browser / API / CLI / local stack;
scenario → expected outcome → actual outcome; commands; passed / failed /
blocked / skipped counts and failure attribution.>

## Release
Release category: <one release:* label>
User impact: <what a user notices; or the internal scope if none>
Compatibility and migration: <none; or the incompatibility and the steps>

The body's Release category: is this project's own convention for carrying the intent — it is not a GitHub instruction and it does not label anything. The label on the pull request is what the release note reads.

Only a change with no user-observable product path (a comment, a pure doc edit) may write not applicable in the E2E section, with a concrete reason. Backend-only is not an exemption; missing credentials or absent coverage are BLOCKED or a coverage gap, not not-applicable. Evidence must be public-safe: no credentials, no local paths, no links a repository reader cannot open. A pull request that must not be merged — a CI experiment, a spike — says so in both the title and the body, and says what would have to be deleted first.

Open it, then read it back

login=$(gh api user --jq .login)
git push -u <fork-remote> HEAD:<branch>
# Keep the braces: in zsh, `$login:chore/…` reads `:c` as a modifier on $login
# (likewise :h, :t, :r, :e), and the head GitHub receives is no longer the branch.
gh pr create --repo openJiuwen-ai/sciencediscovery \
  --draft --base main --head "${login}:<branch>" \
  --title '<type>(<scope>): …' --body-file <file>

gh pr view <n> --repo openJiuwen-ai/sciencediscovery \
  --json number,state,isDraft,baseRefName,headRefName,headRefOid,labels,url
gh pr edit <n> --repo openJiuwen-ai/sciencediscovery --add-label release:<category>

Reading it back is not ceremony. It is how you find out that the head is a branch GitHub deleted when an earlier pull request merged, that the base is not what you meant, or that the diff is empty because the head is already contained in the base.

Keep the pull request as a draft until it is ready. Then mark it ready for review and request review from a code owner listed in .github/CODEOWNERS; an automated review also runs.

gh pr ready <n> --repo openJiuwen-ai/sciencediscovery

Its Actions run

Drafts run policy and L1 in .github/workflows/ci.yml for lightweight static feedback; UT, ST, mocked E2E, Coverage and merge-gate wait until the PR is ready. Marking ready for review (ready_for_review) reruns L1 and starts L2; later pushes and non-draft open/reopen events run them too. Binary and Docker gates run only on the non-PR profiles described in the CI skill.

gh run list --repo openJiuwen-ai/sciencediscovery --branch <branch> --limit 5
gh run view <run-id> --repo openJiuwen-ai/sciencediscovery \
  --json status,conclusion,jobs --jq '.jobs[] | "\(.conclusion // .status)\t\(.name)"'
gh run view <run-id> --repo openJiuwen-ai/sciencediscovery --log-failed

Judge every job, not the aggregate. For E2E read the run summary's counts: Playwright exits 0 on skips, and a BLOCKED journey is reported as skipped, so a green check alone does not mean the journeys ran.

Troubleshooting

Symptom	Meaning
No commits between <base> and <head> and Head ref must be a branch	GitHub could not find the head you named. Two causes; check both before believing the message's claim about the base. The branch was deleted: GitHub removes it when a pull request from it merges, so git ls-remote <fork> 'refs/heads/<branch>' comes back empty. The head string was mangled by zsh: in "$login:chore/…" zsh reads :c as a modifier on $login (likewise :h, :t, :r, :e), so the branch exists but GitHub was asked for <login>hore/… — read the <head> echoed in the message and check it still contains the whole branch name. Which names break depends on the letters after the colon: under zsh 5.9, chore/, feat/, release/ and e2e/ are all mangled while fix/ happens to survive, so a spelling that worked for the last branch proves nothing about this one. Write "${login}:<branch>"; bash accepts both spellings, zsh only the braced one.
The fork's main is hundreds of commits behind	It is a fork nobody syncs. Do not use it as a base and do not push upstream's main to it — on: push: branches: [main] would spend a full CI run on nothing. Base the pull request on a ci/* branch pushed at the upstream commit instead.
A GitHub remote looks diverged with identical files	Separate histories. Compare trees, not SHAs.
The Docker or E2E job fails only on GitHub	Read the job log and the uploaded artifact (docker-compose-logs, e2e-results) before theorising; the product's own startup probe usually already said what was wrong.
A tag push produced no release	The tag did not match .github/workflows/release.yml's filter, which is a glob and not a regex. A non-matching tag fails silently — nothing runs and nothing reports.
The release note's Other Changes is long	Pull requests in the range have no release:* label. Label them before publishing; the section exists to make that visible.