Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🐤 docs: Clarify Maintainer-Directed Canary Pull Requests (#16291)

lia-by-librechat[bot]290e37e5c57b
diff --git a/AGENTS.md b/AGENTS.md
index da0c9b75a8..13d8f4ca20 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,13 +2,24 @@ See CLAUDE.md.
## Branching and pull requests
-Branch off `dev` and target `dev` with every pull request; `gh pr create` defaults to `main`, so
-pass `--base dev` explicitly. `main` is the released branch, kept as a fast-forward of `dev` and
-synced as-is — never open a backport pull request to `main`, because anything merged to `dev`
-reaches it at the next sync. Pull requests opened against `main` are retargeted automatically.
-`Fixes #N` does not close the issue on a `dev` merge — GitHub honors closing keywords only on the
-default branch, so close linked issues by hand. Worktrees share one stash stack, so never use a bare
-`git stash pop`. See the detailed policy in `CLAUDE.md` under "Branching and Pull Requests".
+Normally branch off `dev` and target `dev`; `gh pr create` defaults to `main`, so pass `--base dev`
+explicitly. `main` is the released branch, kept as a fast-forward of `dev` and synced as-is — never
+open a backport pull request to `main`, because anything merged to `dev` reaches it at the next
+sync. Pull requests opened against `main` are retargeted automatically.
+
+**Maintainer-directed canary exception:** Experimental work, or a PR ready to merge after review but
+not yet suitable for the next `main` sync, may instead target `canary`. The maintainer may choose
+this before work starts or while reviewing a stale PR. For new canary work, branch from the current
+`origin/canary` and pass `--base canary` explicitly; do not silently retarget an existing PR or
+promote canary code to `dev`. If a stale PR is redirected to canary, first check its base, diff and
+reviewed head against current canary; coordinate any rebase or new PR with the maintainer. A PR
+explicitly based on `canary` stays there; the main-to-dev retarget workflow does not move it.
+
+Still link related issues in the PR (for example, `Related to #N`) so the work remains
+traceable. `Fixes #N` does not close an issue on a `dev` or `canary` merge — GitHub honors closing
+keywords only on the default branch. Close resolved issues by hand after merging. Worktrees share
+one stash stack, so never use a bare `git stash pop`. See the detailed policy in `CLAUDE.md` under
+"Branching and Pull Requests".
Write the description for a reader who has not followed the branch: what breaks, what triggers it,
how it behaves after the change, then one or two views of the mechanism — a focused diff, a call
diff --git a/CLAUDE.md b/CLAUDE.md
index 52616703f6..0331e00921 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -59,21 +59,36 @@ The source code for `@librechat/agents` (major backend dependency, same team) li
## Branching and Pull Requests
-- **Branch off `dev`, and target `dev` with every pull request.** All work lands on `dev` first.
+- **Normally branch off `dev` and target `dev`.** This is the default for work ready to follow the
+ regular release path. A maintainer-directed canary exception is described below.
- **`main` is the released branch.** It is kept as a fast-forward of `dev` and synced as-is, so it
is always an ancestor of `dev` — equal to it right after a sync, behind it otherwise. It never
carries a commit that `dev` does not have.
- **Never open a backport pull request to `main`.** Anything merged to `dev` reaches `main` at the
next sync; a second pull request for the same change is redundant.
- **The repository's default branch is `main`**, so `gh pr create` and the GitHub UI target it
- unless told otherwise — always pass `--base dev` explicitly.
+ unless told otherwise — pass `--base dev` for normal work or `--base canary` for an explicitly
+ maintainer-directed canary PR.
- Pull requests opened against `main` are retargeted to `dev` automatically by
`.github/workflows/pr-retarget-dev.yml`. The `target: main` label exempts one, as do release-bound
- upstream branches (`dev`, `release/*`, `hotfix/*`). Backport branches are deliberately not exempt —
- a backport merged straight to `main` is what breaks the fast-forward invariant.
-- **`Fixes #N` does not close the issue.** GitHub honors closing keywords only when a pull request
- merges into the default branch (`main`). Merging to `dev` does not close anything, and the later
- fast-forward of `main` is not a merge event either — close linked issues by hand.
+ upstream branches (`dev`, `release/*`, `hotfix/*`). PRs deliberately based on `canary` are not
+ retargeted, including manual sweeps; the script skips them explicitly. Backport branches are
+ deliberately not exempt — a backport merged straight to `main` breaks the fast-forward invariant.
+- **Canary is an explicit, maintainer-selected integration target, not a path that automatically
+ flows to `dev` or `main`.** Experimental changes and PRs that are ready to merge following review
+ but must not enter the next `main` sync can go to `canary`. The maintainer may decide this when
+ assigning the work or while reviewing an older/stale PR. For a new canary PR, branch from the
+ current `origin/canary` and set `--base canary`. Never infer that a canary-targeted PR should move
+ to `dev` just because `dev` is the default; do not copy canary features into `dev` without an
+ explicit maintainer decision. If a stale PR is reassigned to canary, check the PR's base, diff and
+ exact reviewed head against current canary before changing its base or proposing a new canary
+ branch/PR; if a rebase changes the head, verify and review that new head before merging.
+- **Link related issues in the PR even when they will not auto-close.** Reference each relevant
+ issue in the description (for example, `Related to #N`) so reviewers can find the context and
+ track the work. GitHub honors `Fixes #N` and other closing keywords only when a pull request
+ merges into the default branch (`main`). Merging to `dev` or `canary` does not close an issue,
+ and the later fast-forward of `main` is not a merge event either — close resolved issues by hand
+ after merging.
- **Git worktrees share one stash stack.** `refs/stash` lives in the common `.git` directory, so a
bare `git stash pop` in one worktree can take work stashed in another. Prefer a throwaway WIP
commit; if you must stash, `git stash push -m <tag>` and `apply` that specific entry.