diff --git a/docs/_sidebar_diataxis.json b/docs/_sidebar_diataxis.json index 9cc8d15d85..b45b7790fb 100644 --- a/docs/_sidebar_diataxis.json +++ b/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", diff --git a/docs/how-to/advanced/several-versions.md b/docs/how-to/advanced/several-versions.md new file mode 100644 index 0000000000..a4c2209c6d --- /dev/null +++ b/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. + +::: diff --git a/docs/maintainer/updating_pkgs.md b/docs/maintainer/updating_pkgs.md index f119b12ada..dae1737078 100644 --- a/docs/maintainer/updating_pkgs.md +++ b/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