From 3ee332a633431c79a4891a332a96211ecce36246 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 21 Nov 2025 17:16:24 +0100 Subject: [PATCH 1/7] How to: sync your fork --- docs/_sidebar_diataxis.json | 5 +++++ docs/how-to/basics/fork-sync.md | 36 +++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 docs/how-to/basics/fork-sync.md diff --git a/docs/_sidebar_diataxis.json b/docs/_sidebar_diataxis.json index 85e4319dcd..cf855c05b0 100644 --- a/docs/_sidebar_diataxis.json +++ b/docs/_sidebar_diataxis.json @@ -68,6 +68,11 @@ "type": "link", "label": "Rerender a feedstock", "href": "/docs/maintainer/updating_pkgs/#rerendering-feedstocks" + }, + { + "type": "doc", + "label": "Keep your fork in sync", + "id": "how-to/basics/fork-sync" } ] }, diff --git a/docs/how-to/basics/fork-sync.md b/docs/how-to/basics/fork-sync.md new file mode 100644 index 0000000000..3bd07d45be --- /dev/null +++ b/docs/how-to/basics/fork-sync.md @@ -0,0 +1,36 @@ +--- +tags: [how-to, basic] +--- + +# How to keep your fork in sync + +The `conda-forge` workflow assumes that contributors will _always_ open their pull requests from their feedstock fork. Follow these best practices to make sure your branches are always up-to-date. + +## Terminology + +Given a `conda-forge/package-feedstock` repository, Github allows you to create a copy on your account, called _fork_. You have full rights over your forked repository, and it should be the place where you experiment with new branches and changes. + +The original repository is usually referred to as `upstream`. + +## How to fork a feedstock + +Forks are easily created from the Github UI: + +1. Go to the conda-forge feedstock +2. Click on the Fork button in the top right corner +3. Select on which account you want to create the fork. Choose your personal account, not an organization. + +## How to keep your fork in sync + +Never push directly to your fork's `main` branch. This branch should always be identical to upstream. This way your new branches will never start with merge conflicts. + +You can sync your fork `main` with upstream's via the Github UI. Look for an option named "Sync". Then, in your local copy of the forked repository, run: `git checkout main && git pull`. + +Locally, you can follow these steps: + +1. If not available on disk yet, clone your fork and change into its directory. +2. Change the branch to `main`: `git checkout main`. +3. Pull from upstream: `git pull upstream main`. + - If this results in merge conflicts, abort with `git merge --abort` and hard-reset `main`. This WILL lose all the changes made in `main` that were not part of upstream. The command is: `git reset --hard upstream/main`. + +Once `main` is synced, you can create a new branch with `git checkout -b new-branch-name`. From 244a23f67414c99d5aded26f11f0e7aedc504e78 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Mon, 1 Dec 2025 09:36:35 +0100 Subject: [PATCH 2/7] more info on conflict resolution --- docs/how-to/basics/fork-sync.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/how-to/basics/fork-sync.md b/docs/how-to/basics/fork-sync.md index 3bd07d45be..4b283f1b5b 100644 --- a/docs/how-to/basics/fork-sync.md +++ b/docs/how-to/basics/fork-sync.md @@ -31,6 +31,20 @@ Locally, you can follow these steps: 1. If not available on disk yet, clone your fork and change into its directory. 2. Change the branch to `main`: `git checkout main`. 3. Pull from upstream: `git pull upstream main`. - - If this results in merge conflicts, abort with `git merge --abort` and hard-reset `main`. This WILL lose all the changes made in `main` that were not part of upstream. The command is: `git reset --hard upstream/main`. + +If this results in merge conflicts, check the section below. Once `main` is synced, you can create a new branch with `git checkout -b new-branch-name`. + +## How to resolve conflicts in `main` + +When pulling from `upstream`, you might run into merge conflicts. This can happen if you pushed to your fork's `main` and opened a PR from that branch instead of creating a new one. + +To make your fork's `main` look like `upstream`'s: + +1. If you just tried to `pull`, abort with `git merge --abort`. Otherwise, check the info in `git status` and make sure you are you are in the `main` branch: `git checkout main`. +2. Park your local `main` in separate branch, as a backup: `git checkout -b parked-changes`. +3. Ensure your remotes are fresh: `git fetch upstream`. +4. Go back to `main` and reset it to `upstream`'s: `git reset --hard upstream/main`. + +Alternatively, create a backup of your `main` branch with `git checkout main && git checkout -b parked-changes` and then try to pull with a rebase strategy with `git pull --rebase upstream main`. The idea here is to keep only the commits from `upstream` and drop the ones you added yourself. [Gitlab's docs on `git rebase`](https://docs.gitlab.com/topics/git/git_rebase/) contain more details on this type of workflow. From 79a687f0afce8fb36d6979cd8af156bc168e38e0 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Mon, 1 Dec 2025 15:39:35 +0100 Subject: [PATCH 3/7] Update docs/how-to/basics/fork-sync.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Górny --- docs/how-to/basics/fork-sync.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/basics/fork-sync.md b/docs/how-to/basics/fork-sync.md index 4b283f1b5b..198966836f 100644 --- a/docs/how-to/basics/fork-sync.md +++ b/docs/how-to/basics/fork-sync.md @@ -30,9 +30,9 @@ Locally, you can follow these steps: 1. If not available on disk yet, clone your fork and change into its directory. 2. Change the branch to `main`: `git checkout main`. -3. Pull from upstream: `git pull upstream main`. +3. Pull from upstream: `git pull --ff-only upstream main`. -If this results in merge conflicts, check the section below. +If this results in a "not possible to fast-forward" error, check the section below. Once `main` is synced, you can create a new branch with `git checkout -b new-branch-name`. From 93a1dc160c5d36244e0c1113315d1f4bf787fc9a Mon Sep 17 00:00:00 2001 From: jaimergp Date: Mon, 1 Dec 2025 15:41:56 +0100 Subject: [PATCH 4/7] adjust some wording --- docs/how-to/basics/fork-sync.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/how-to/basics/fork-sync.md b/docs/how-to/basics/fork-sync.md index 198966836f..bd39aa700b 100644 --- a/docs/how-to/basics/fork-sync.md +++ b/docs/how-to/basics/fork-sync.md @@ -32,19 +32,19 @@ Locally, you can follow these steps: 2. Change the branch to `main`: `git checkout main`. 3. Pull from upstream: `git pull --ff-only upstream main`. -If this results in a "not possible to fast-forward" error, check the section below. +If this results in a "not possible to fast-forward" error, check [the section below](#how-to-resolve-conflicts-in-main). Once `main` is synced, you can create a new branch with `git checkout -b new-branch-name`. ## How to resolve conflicts in `main` -When pulling from `upstream`, you might run into merge conflicts. This can happen if you pushed to your fork's `main` and opened a PR from that branch instead of creating a new one. +When pulling from `upstream`, you might run into merge conflicts or "not possible to fast-forward" errors. This can happen if you pushed to your fork's `main` branch instead of creating a new one. -To make your fork's `main` look like `upstream`'s: +To make your fork's `main` identical to `upstream`'s: -1. If you just tried to `pull`, abort with `git merge --abort`. Otherwise, check the info in `git status` and make sure you are you are in the `main` branch: `git checkout main`. +1. If you just tried to `pull` and got merge conflicts, abort with `git merge --abort`. Otherwise, check the info in `git status` and make sure you are you are in the `main` branch: `git checkout main`. 2. Park your local `main` in separate branch, as a backup: `git checkout -b parked-changes`. 3. Ensure your remotes are fresh: `git fetch upstream`. -4. Go back to `main` and reset it to `upstream`'s: `git reset --hard upstream/main`. +4. Go back to `main` and reset it to `upstream`'s: `git checkout main && git reset --hard upstream/main`. Alternatively, create a backup of your `main` branch with `git checkout main && git checkout -b parked-changes` and then try to pull with a rebase strategy with `git pull --rebase upstream main`. The idea here is to keep only the commits from `upstream` and drop the ones you added yourself. [Gitlab's docs on `git rebase`](https://docs.gitlab.com/topics/git/git_rebase/) contain more details on this type of workflow. From 958e85b28d5f3563f5a19650ba3ee15e6f579ae1 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Wed, 3 Dec 2025 13:34:00 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: h-vetinari --- docs/how-to/basics/fork-sync.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/how-to/basics/fork-sync.md b/docs/how-to/basics/fork-sync.md index bd39aa700b..23b37ef268 100644 --- a/docs/how-to/basics/fork-sync.md +++ b/docs/how-to/basics/fork-sync.md @@ -40,11 +40,15 @@ Once `main` is synced, you can create a new branch with `git checkout -b new-bra When pulling from `upstream`, you might run into merge conflicts or "not possible to fast-forward" errors. This can happen if you pushed to your fork's `main` branch instead of creating a new one. -To make your fork's `main` identical to `upstream`'s: +If you don't care about your local changes, you can simply do `git reset --hard upstream/main`. +If you want to save your changes but still make your fork's `main` identical to `upstream`'s: 1. If you just tried to `pull` and got merge conflicts, abort with `git merge --abort`. Otherwise, check the info in `git status` and make sure you are you are in the `main` branch: `git checkout main`. 2. Park your local `main` in separate branch, as a backup: `git checkout -b parked-changes`. 3. Ensure your remotes are fresh: `git fetch upstream`. 4. Go back to `main` and reset it to `upstream`'s: `git checkout main && git reset --hard upstream/main`. -Alternatively, create a backup of your `main` branch with `git checkout main && git checkout -b parked-changes` and then try to pull with a rebase strategy with `git pull --rebase upstream main`. The idea here is to keep only the commits from `upstream` and drop the ones you added yourself. [Gitlab's docs on `git rebase`](https://docs.gitlab.com/topics/git/git_rebase/) contain more details on this type of workflow. +Alternatively, create a backup of your `main` branch with `git checkout main && git checkout -b parked-changes` +and then try to pull with a rebase strategy with `git rebase -i upstream/main`. +The idea here is to keep only the commits from `upstream` and drop the ones you added yourself. +[Gitlab's docs on `git rebase`](https://docs.gitlab.com/topics/git/git_rebase/) contain more details on this type of workflow. From d53d582b004a9a72aaadbf470532d4dab2d0d015 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Wed, 3 Dec 2025 15:03:51 +0100 Subject: [PATCH 6/7] Update docs/how-to/basics/fork-sync.md Co-authored-by: h-vetinari --- docs/how-to/basics/fork-sync.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/how-to/basics/fork-sync.md b/docs/how-to/basics/fork-sync.md index 23b37ef268..b6d64466e8 100644 --- a/docs/how-to/basics/fork-sync.md +++ b/docs/how-to/basics/fork-sync.md @@ -50,5 +50,6 @@ If you want to save your changes but still make your fork's `main` identical to Alternatively, create a backup of your `main` branch with `git checkout main && git checkout -b parked-changes` and then try to pull with a rebase strategy with `git rebase -i upstream/main`. -The idea here is to keep only the commits from `upstream` and drop the ones you added yourself. +The idea here is to replay the commits you want to keep on top of the `upstream/main` branch, while dropping +those that have become obsolete (or are otherwise conflict-prone, like rerender commits). [Gitlab's docs on `git rebase`](https://docs.gitlab.com/topics/git/git_rebase/) contain more details on this type of workflow. From 39e3e6c7f0a891f0f06ede10cd0bd6fdf3e271a6 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Fri, 5 Dec 2025 11:19:45 +0100 Subject: [PATCH 7/7] Update docs/how-to/basics/fork-sync.md Co-authored-by: h-vetinari --- docs/how-to/basics/fork-sync.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/basics/fork-sync.md b/docs/how-to/basics/fork-sync.md index b6d64466e8..6420f57f9a 100644 --- a/docs/how-to/basics/fork-sync.md +++ b/docs/how-to/basics/fork-sync.md @@ -40,7 +40,7 @@ Once `main` is synced, you can create a new branch with `git checkout -b new-bra When pulling from `upstream`, you might run into merge conflicts or "not possible to fast-forward" errors. This can happen if you pushed to your fork's `main` branch instead of creating a new one. -If you don't care about your local changes, you can simply do `git reset --hard upstream/main`. +If you don't care about your local changes, you can simply do `git checkout main && git reset --hard upstream/main`. If you want to save your changes but still make your fork's `main` identical to `upstream`'s: 1. If you just tried to `pull` and got merge conflicts, abort with `git merge --abort`. Otherwise, check the info in `git status` and make sure you are you are in the `main` branch: `git checkout main`.