How to: Maintain several versions (#2661)

Co-authored-by: Michał Górny <[email protected]>

Author: jaimergp

docs/_sidebar_diataxis.json

@@ -115,9 +115,9 @@
             "href": "/docs/maintainer/knowledge_base/#multi-output-recipes"
           },
           {
-            "type": "link",
+            "type": "doc",
             "label": "Maintain several versions",
-            "href": "/docs/maintainer/updating_pkgs/#maintaining-several-versions"
+            "id": "how-to/advanced/several-versions"
           },
           {
             "type": "link",

docs/how-to/advanced/several-versions.md

@@ -0,0 +1,58 @@
+---
+tags: [how-to, advanced]
+---
+
+# How to maintain several versions
+
+The conda-forge workflow assumes that a push to any branch in the feedstock repository will result in a build being uploaded to the conda-forge channel (and that's why PRs must always be opened from a fork!).
+
+Most feedstocks only need `main` for their builds, since the package has a single release line, and new releases always imply a later version. However, some packages may maintain a few release lines in parallel. If you wish to maintain those in your feedstock, you will need to create a branch for each.
+
+## Create the new branch
+
+:::note
+This operation can only be performed by users with write acccess to the feedstock.
+:::
+
+In the local copy of your [forked repository](../basics/fork-sync.md), create a branch named after the release line you want to maintain. For example, for `3.10`, it could be:
+
+```bash
+git checkout main
+git pull upstream main
+git checkout -b v3.10.x
+```
+
+Add an empty commit with the `[ci skip]` message so the new branch does not result in a new build process, and push it to `upstream`. This is one of the rare ocassions where you must push directly to the feedstock, not your fork!
+
+```bash
+git commit --allow-empty -m "[ci skip] Create new branch for v3.10.x release series"
+git push -u upstream v3.10.x
+```
+
+Now, this branch can be selected as a target branch in the following steps.
+
+## Open a PR with the necessary changes
+
+From the same branch, create another one to add some extra changes that will need to be reviewed in a PR:
+
+```bash
+git checkout -b setup-3.10.x
+```
+
+Open your `conda-forge.yml` file and add these lines:
+
+```yaml
+bot:
+  abi_migration_branches:
+    - "v3.10.x"  # or the branch name you picked
+```
+
+And [rerender](../basics/rerender.md). Now, make sure to adjust the recipe file so the correct version is being built.
+
+Once ready, push the branch to your fork (`origin`) and open the corresponding pull request. Don't forget to pick `v3.10.x` as the target branch!
+
+:::note
+
+In some cases, the `abi_migration_branches` may receive migration PRs that have already been processed. This is being looked into at [regro/cf-scripts#2500](https://github.com/regro/cf-scripts/issues/2500). In the meantime, you can ignore these redundant PRs by closing them.
+
+:::

docs/maintainer/updating_pkgs.md

@@ -304,11 +304,7 @@ For an example see [this](https://github.com/conda-forge/cudnn-feedstock/issues/
 
 ## Maintaining several versions
 
-If you'd like to maintain more than one version of your package, you can use branches on the feedstock. To do this:
-
-- Fork your feedstock and make a meaningful branch name (e.g., v1.X or v1.0).
-- Make the required changes to the recipe and rerender the feedstock.
-- Then push this branch from your fork to the upstream feedstock. Our CI services will automatically build any branches in addition to the default branch.
+See [How to maintain several versions](/docs/how-to/advanced/several-versions.md).
 
 ## Troubleshooting