Standardize git remote naming on upstream/origin across docs and tooling#65629
Open
potiuk wants to merge 4 commits intoapache:mainfrom
Open
Standardize git remote naming on upstream/origin across docs and tooling#65629potiuk wants to merge 4 commits intoapache:mainfrom
potiuk wants to merge 4 commits intoapache:mainfrom
Conversation
potiuk
requested review from
amoghrajesh,
ashb,
bugraoz93,
choo121600,
ephraimbuddy,
gopidesupavan,
jason810496,
jedcunningham,
jscheffl,
kaxil,
shahar1,
vatsrahul1001 and
vincbeck
as code owners
boring-cyborg
Bot
added
area:dev-tools
backport-to-v3-2-test
jscheffl
reviewed
Apr 21, 2026
o-nikolas
reviewed
Apr 21, 2026
Airflow's contributing docs, release runbooks, and agent instructions used a mix of `apache`, `origin`, and placeholder names for the git remote that tracks `apache/airflow`. Standardize on `upstream` → `apache/airflow` and `origin` → the contributor's fork throughout — the two names already assumed by `dev/sync_fork.sh` and by most beginner-facing docs — so that contributors, release managers, and agents follow a single convention. - Add a new "Git remote naming conventions" section to `contributing-docs/10_working_with_git.rst` with migration commands for the common legacy layouts (`apache` remote, origin-as-upstream, missing upstream/fork). - Update `contributing-docs/10_working_with_git.rst`, `contributing-docs/18_contribution_workflow.rst`, and all `dev/README_RELEASE_*.md` runbooks to use `upstream` in examples and link to the conventions section. - Update `AGENTS.md` (= `CLAUDE.md`) to document the convention and instruct agents to surface remote-name mismatches to the user and propose concrete `git remote rename` commands instead of silently using whatever names they find. - Switch breeze CLI defaults and error messages to match: `--remote-name` now defaults to `upstream` in `release-management start-rc-process`, `release-management update-constraints`, and `sbom update-sbom-information`; `breeze ci find-backport-prs` warns about a missing `upstream` (not `apache`) remote; the fallback list in `tag_providers` now tries `upstream` first and keeps `apache`/`origin` for back-compat. - Regenerate the affected breeze help images and update the `basic-tests.yml` CI workflow to add `upstream` rather than `apache`.
@o-nikolas pointed out that the new "never push directly to main on either remote" phrasing in the Git remote naming conventions section was stricter than the long-standing guidance in 18_contribution_workflow.rst, which explicitly tolerates developing directly on your fork's main and opening a PR from there. Align the conventions section with the more permissive stance and cross-link to the Contribution Workflow step so both places say the same thing. AGENTS.md keeps the stricter "no pushes to main" rule because that advice is aimed at automated agents where branch-only workflows are the right default.
potiuk
force-pushed
the
standardize-git-remote-conventions
branch
from
f2d0d42 to
417e4ef
Compare
Dev-iL
approved these changes
Apr 22, 2026
| naming convention — see | ||
| [`contributing-docs/10_working_with_git.rst`](../contributing-docs/10_working_with_git.rst#git-remote-naming-conventions)). | ||
| You can override this by passing `--remote-name` option to the command. | ||
| 3. You need to run `breeze release-management update-constraints` command. The `breeze` command comes usually |
Collaborator
There was a problem hiding this comment.
Consider rewriting this bullet to avoid using "usually" twice. Suggestions by gemini:
- Option 1 (Direct):
You need to run thebreeze release-management update-constraintscommand. Typically,breezeis run from a separate clone of the Airflow repository, specifically from the main branch.
- Option 2 (Concise):
Run thebreeze release-management update-constraintscommand. This usually stems from another clone of the Airflow repository (often the main branch). - Option 3 (Action-oriented):
You need to runbreeze release-management update-constraints. Note that thebreezecommand generally comes from a different Airflow clone, specifically the one tracking the main branch.
Member
Author
There was a problem hiding this comment.
Applied option 1 ("Typically, breeze is run from a separate clone of the Airflow repository, on the main branch.") in 475f8ff — thanks!
eladkal
approved these changes
Apr 22, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Standardizes the naming convention of git remotes across Airflow docs and Breeze tooling so contributors and release managers consistently use upstream for apache/airflow and origin for forks.
Changes:
- Updates Breeze CLI defaults/messages to prefer
upstream(with some back-compat fallbacks). - Rewrites contributing + release documentation examples to use
upstream/origin, adding a dedicated conventions section. - Regenerates Breeze CLI help output artifacts and updates CI workflow setup to add/fetch
upstream.
Reviewed changes
Copilot reviewed 19 out of 22 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| dev/breeze/src/airflow_breeze/utils/github.py | Switches default remote used for tag discovery to upstream and updates user guidance text. |
| dev/breeze/src/airflow_breeze/commands/sbom_commands.py | Changes --remote-name default and help text to align with upstream convention. |
| dev/breeze/src/airflow_breeze/commands/release_management_commands.py | Updates remote fallback order and defaults to prefer upstream while retaining legacy fallbacks. |
| dev/breeze/src/airflow_breeze/commands/release_candidate_command.py | Changes release-candidate --remote-name default to upstream and clarifies intent in help. |
| dev/breeze/src/airflow_breeze/commands/ci_commands.py | Updates warning message to reference the upstream convention. |
| dev/breeze/doc/images/output_sbom_update-sbom-information.txt | Regenerated Breeze help output checksum for SBOM command. |
| dev/breeze/doc/images/output_sbom_update-sbom-information.svg | Regenerated Breeze help image reflecting new defaults/help text. |
| dev/breeze/doc/images/output_release-management_update-constraints.txt | Regenerated Breeze help output checksum for release-management command. |
| dev/breeze/doc/images/output_release-management_update-constraints.svg | Regenerated Breeze help image reflecting new defaults/help text. |
| dev/breeze/doc/images/output_release-management_start-rc-process.txt | Regenerated Breeze help output checksum for start-rc-process. |
| dev/breeze/doc/images/output_release-management_start-rc-process.svg | Regenerated Breeze help image reflecting new defaults/help text. |
| dev/breeze/doc/adr/0003-bootstrapping-virtual-environment.md | Updates ADR example to reference upstream/main. |
| dev/README_RELEASE_PYTHON_CLIENT.md | Updates push/fetch/tag instructions to use upstream and links to conventions. |
| dev/README_RELEASE_PROVIDERS.md | Updates provider release/tagging instructions to use upstream and references conventions. |
| dev/README_RELEASE_HELM_CHART.md | Updates helm chart release workflow to use upstream. |
| dev/README_RELEASE_AIRFLOWCTL.md | Updates airflow-ctl release workflow examples to use upstream/origin. |
| dev/README_RELEASE_AIRFLOW.md | Updates release-manager runbook to assume upstream and explains how to migrate. |
| dev/MANUALLY_GENERATING_IMAGE_CACHE_AND_CONSTRAINTS.md | Updates constraints/image-cache instructions to default to upstream. |
| contributing-docs/18_contribution_workflow.rst | Updates contributor workflow to reference upstream/main and conventions section. |
| contributing-docs/10_working_with_git.rst | Adds “Git remote naming conventions” section and updates rebase/sync examples to upstream. |
| AGENTS.md | Adds explicit remote naming convention guidance for agents and updates push/rebase instructions. |
| .github/workflows/basic-tests.yml | Updates canary test job to add/fetch upstream instead of apache. |
Comment on lines
+186
to
+191
| 1. You first need to add the Apache project remote to your git repository. This is only necessary once, | ||
| so if it's not the first time you are following this tutorial you can skip this step. In this example, | ||
| we will be adding the remote as "apache" so you can refer to it easily | ||
| so if it's not the first time you are following this tutorial you can skip this step. Per the | ||
| `Git remote naming conventions`_ we add it as ``upstream``: | ||
|
|
||
| * If you use ssh: ``git remote add apache git@github.com:apache/airflow.git`` | ||
| * If you use https: ``git remote add apache https://github.com/apache/airflow.git`` | ||
| * If you use ssh: ``git remote add upstream git@github.com:apache/airflow.git`` | ||
| * If you use https: ``git remote add upstream https://github.com/apache/airflow.git`` |
There was a problem hiding this comment.
In the numbered rebase steps, the continuation lines and the nested bullet list under step 1 are not indented, which breaks the reStructuredText list structure (the bullets/paragraphs will render outside the "1." item). Indent the wrapped paragraph lines and the * If you use ... bullets to be part of step 1 (typically 3 spaces past the list marker) so Sphinx renders the list correctly.
Member
Author
There was a problem hiding this comment.
Indented the wrapped paragraph and both bullets under step 1 to 3 spaces so the list renders correctly in Sphinx. Fixed in 475f8ff.
Comment on lines
200
to
203
| "--remote-name", | ||
| type=NotVerifiedBetterChoice(["apache", "origin"]), | ||
| default="apache", | ||
| type=NotVerifiedBetterChoice(["upstream", "origin"]), | ||
| default="upstream", | ||
| show_default=True, |
There was a problem hiding this comment.
NotVerifiedBetterChoice is used for shell completion and help output; removing apache from the choices means existing setups that still use an apache remote won't see it suggested/shown in --help even though the value is still accepted. Consider keeping apache in the choices list (while defaulting to upstream) to preserve discoverability/back-compat during the transition.
Member
Author
There was a problem hiding this comment.
Good point — kept apache in the NotVerifiedBetterChoice list for autocomplete/--help discoverability during the transition, with a code comment noting why. Runtime acceptance of arbitrary values is unchanged. 475f8ff.
pierrejeambrun
approved these changes
Apr 22, 2026
hussein-awala
approved these changes
Apr 22, 2026
Co-authored-by: Dev-iL <6509619+Dev-iL@users.noreply.github.com>
vincbeck
approved these changes
Apr 22, 2026
- 10_working_with_git.rst: indent the wrapped paragraph and bullet list under step 1 so Sphinx renders them inside the "1." item instead of floating outside (flagged by Copilot — the existing step 2+ wraps already follow this indent rule). - MANUALLY_GENERATING_IMAGE_CACHE_AND_CONSTRAINTS.md: replace the double "usually" with a single "Typically" (Dev-iL). - sbom_commands.py: add ``apache`` back to NotVerifiedBetterChoice's autocomplete/help list so legacy clones still see it in --help during the upstream/origin transition. Any remote name is still accepted at runtime since the type is "NotVerified" (Copilot). Regenerated the sbom help-text SVGs.
bugraoz93
approved these changes
Apr 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Airflow's contributing docs, release runbooks, and agent instructions used
a mix of
apache,origin, and placeholder names for the git remote thattracks
apache/airflow. This PR standardizes onupstream→apache/airflowand
origin→ the contributor's fork throughout — the two names alreadyassumed by
dev/sync_fork.shand by most beginner-facing docs — so thatcontributors, release managers, and agents follow a single convention.
What changed
contributing-docs/10_working_with_git.rstwith migration commands forcommon legacy layouts (
apacheremote,origin-as-upstream, missingupstream/fork).
10_working_with_git.rstand18_contribution_workflow.rstnow use
upstreamin all fetch/rebase/reset examples.dev/README_RELEASE_AIRFLOW.md,README_RELEASE_AIRFLOWCTL.md,README_RELEASE_HELM_CHART.md,README_RELEASE_PROVIDERS.md,README_RELEASE_PYTHON_CLIENT.md, andMANUALLY_GENERATING_IMAGE_CACHE_AND_CONSTRAINTS.mdswitched fromapache/origin-as-upstream toupstream, with a pointer to the newconventions section.
AGENTS.md/CLAUDE.md): added a conventionssection and instructed agents to surface remote-name mismatches to the
user and propose concrete
git remote renamecommands rather thansilently going along with whatever names the checkout uses.
--remote-namenow defaults toupstreaminrelease-management start-rc-process,release-management update-constraints, andsbom update-sbom-information.breeze ci find-backport-prswarnsabout a missing
upstream(notapache) remote. The fallback list intag_providerstriesupstreamfirst and keepsapache/originforback-compat so existing release-manager setups keep working.
.github/workflows/basic-tests.ymladdsupstream(notapache); regenerated the affected breeze help images.Test plan
prek run --from-ref upstream/main --stage pre-commit— all hooks passgrepsweep confirms nogit remote add/fetch/push/pull/rebase apacheor
apache/main/apache/v*-testreferences remain in contributingdocs, release docs,
AGENTS.md, ordev/breeze/doc/--remote-namedefaultsWas generative AI tooling used to co-author this PR?
Generated-by: Claude Code (Opus 4.7, 1M context) following the guidelines