conda-forge are immutable¶
As a matter of policy, we do not allow edits or the deletion of packages on
policy is very important as it increases the reliability and reproducibility of
made with the
conda-forge channel. Note that because of this policy, our upload scripts will refuse to
upload packages which already exist on the
If you need to remove a package, please see the section on marking packages broken.
Forking and pull requests¶
All maintainers are given push access to the feedstocks that they maintain. This means that a maintainer can create branches in the main repo. For updates, using a branch in the main repo is discouraged because,
CI is run on both the branch and the PR.
This wastes CI resources
Branches are automatically published.
This means if you push a version update to a branch and then create a PR, conda packages will be published to anaconda.org before the PR is merged.
For these reasons, maintainers are asked to fork the feedstock to their personal account, push to a branch in the fork and then open a PR to the
Pushing to regro-cf-autotick-bot branch¶
When a new version of a package is released on PyPI/CRAN/.., we have a bot that automatically creates version updates for the feedstock. In most cases you can simply merge this PR and it should include all changes. When certain things have changed upstream, e.g. the dependencies, you will still have to do changes to the created PR. As feedstock maintainer, you don’t have to create a new PR for that but can simply push to the branch the bot created. There are two alternatives to push to the branch of the bot:
Manually setting up git remotes:
Clone the conda-forge feedstock repository
Add the remote of the bot:
git remote add regro-cf-autotick-bot firstname.lastname@example.org:regro-cf-autotick-bot/<package>-feedstock.git
Fetch the remote:
git fetch regro-cf-autotick-bot
Checkout the branch of the PR, git should automatically link it to the regro-cf-autotick-bot remote if this is the only remote with a branch of that name.
If there are multiple remotes with this branch name, you need to first checkout the remote branch and then turn it into a local branch:
git checkout regro-cf-autotick-bot/<branch> && git checkout -b <branch>
Commit and push on that branch, if the remote was not correctly setup, use
git push -u regro-cf-autotick-bot <branch>.
Using Github’s hub tool (which conda-forge ships!
conda install hub -c conda-forge):
Clone the conda-forge feedstock repository
Checkout the correct branch with remote:
hub pr checkout 12where
12is the ID of the PR.
Commit and push on this branch, the remote is automatically set up to push to regro-cf-autotick-bot’s fork.
Example workflow for updating a package¶
Here we assume that you would like to update the feedstock
<feedstock>. Feedstock is a placeholder and can e.g. be replaced by
Forking the feedstock
Before you can submit your first PR, you have to fork conda-forge’s feedstock.
Navigate to https://github.com/conda-forge/<feedstock> in your favorite web browser and click the
You now have a clone of the feedstock in
https://github.com/<your-github-id>/<feedstock>under your control.
Connect to the feedstock from your computer by using
git clone https://github.com/<your-github-id>/<feedstock>.
Syncing your fork with conda-forges feedstock
This step is only required if you have forked some time ago and your fork is missing commits from the feedstock at conda-forge.
Make sure you are on the master branch:
git checkout master
Register conda-forge’s feedstock with
git remote add upstream https://github.com/conda-forge/<feedstock>
Fetch the latest updates with
git fetch upstream
Pull in the latest changes into your master branch:
git rebase upstream/master
Creating your changes in a new branch
Now you are ready to update the recipe
Create and switch to a new branch:
git checkout -b <branch-name>.
<branch-name>can be e.g.
Make your changes locally
Review your changes then use
git add <changed-files>. Where
<changed-files>are a whitespace separated list of filenames you changed.
Create a commit by
git commit -m <commit-msg>, where
updated feedstock to version 1.0.1
Pushing your changes to GitHub and propose a PR
Push the branch with changes to your fork on GitHub:
git push origin <branch-name>
Create a pull request via the web interface by navigating to
https://github.com/<your-github-id>/<feedstock>with your web browser and clicking the button
create pull request.
Please follow the following guidelines while updating recipes:
Always use a fork of the feedstock while updating the recipe.
When a package’s version is not changed, but other metadata or parts of the recipe are changed, increase the build number by
While shipping a new version of your package, reset the build number to
Rerendering is conda-forge’s way to update the files common to all feedstocks (e.g. README, CI configuration, pinned dependencies).
Rerendering can be done in two ways:
Rerendering with conda-smithy locally¶
The first step is to install
conda-smithy in your root environment.
conda install -c conda-forge conda-smithy
Commit all changes and from the root directory of the feedstock, type:
conda smithy rerender -c auto
Optionally one can commit the changes manually.
To do this drop
-c auto from the command.
When to rerender¶
We need to re-render when there are changes in the following parts of the feedstock:
Platform configuration (
Updates in the build matrix due to new versions of Python, NumPy, PERL, R, etc.
Updates in conda-forge pinning that affect the feedstock.
Build issues that a feedstock configuration update will fix (follow us on gitter to know about those).
Testing changes locally¶
If you have docker installed on your system, you can test builds locally on your machine under the same settings as it is built by our CI.
If you want to build and test updates to a feedstock locally, go to the root feedstock directory and run:
This will prompt you to choose one of the
*.yaml config files in
.ci_support/. Note that
shyaml is needed to parse the
docker_image from these files. Otherwise the build will use the default
Alternatively, you can specify ahead which config to use with e.g. (assuming you wish to build and test python 3.6 on Linux, and such a config file exists at
python build-locally.py linux_python3.6
Note that for long build logs one can do
python build-locally.py 2>&1 | tee log.txt
to save it in a text file for future inspection.
Once built, you can find the finished package in the
build_artifacts directory in your feedstock.
Removing broken packages¶
Sometimes mistakes happen and a broken package ends up being uploaded to the conda-forge channel.
If the only issue is in the package metadata, we can directly patch it using the repo data patches feedstock. Please make a PR there to add a patch. In order to ensure future versions have the required changes, you also need to change the recipe to reflect the metadata changes.
If instead the actual contents of the package are broken, the following steps will
remove broken packages from the
Locate the paths to broken files on anaconda.org, by searching for the conda-forge package and switching to the files tab.
Fork conda-forge/admin-requests and add a new text file in the
Add the broken files to the new text file, one path per line. See broken/example.txt for an example file.
Open a new PR. Once merged, a bot will label all listed files as broken, thus effectively removing them from the channel.
If a package is no longer maintained
conda-forge will archive
the repository. An archived repository can no longer accept PRs and issues, which prevents people and
regro-cf-autotick-bot from updating the
package (an example would be to re-render the feedstock to support new Python versions). Note that this does not remove the existing packages, those will still be available.
If you believe a feedstock should be archived, please contact @conda-forge/core.
Updating the maintainer list¶
The list of maintainers of a feedstock is recorded in the recipe itself. A new maintainer can be added by opening an issue in the feedstock repository with the following title:
@conda-forge-admin, please add user @username
username is the username of the new maintainer to be added.
A PR will be automatically created and a maintainer or a member of the
core team, in case no maintainer is active anymore, can then merge this PR to add the user.
To contact core, ping them by mentioning @conda-forge/core in a comment or, if you haven’t heard back in a while or are new to conda-forge, contact them through the community gitter.
This PR is designed to skip building the package. Please do not modify it or adjust the commit message.
For an example see this issue.
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.