LICENSE Documentation

1. Project Overview & Quickstart (conda-forge/LICENSE)

LICENSE

Open-source repository conda-forge/LICENSE

Repository Details

Repository: conda-forge/LICENSE
Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (conda-forge/conda-forge.github.io)

File: README.md

[conda-forge.org](https://conda-forge.org)

Overview

This repository

is the home of the source code of conda-forge's documentation.
is the home of the source code of conda-forge's status dashboard.
provides an issue tracker for conda-forge related questions and issues that are not specific to individual feedstocks.

If you have questions or need help, please check out our documentation for a list of ways to interact with us.

Improving the docs

You can help to improve the documentation! It is version-controlled in the conda-forge.github.io repository on GitHub.
The docs are built on GitHub Actions and run the .ci_scripts/update_docs script.
We are glad to know that you would like to contribute. To build the docs locally, follow the steps mentioned below:

Fork the conda-forge.github.io repository to your own GitHub user account.
Clone this fork onto your computer.
Go into the cloned folder and:
- If you are using pixi:
  - Use pixi run start for live builds
  - Use pixi run build-production for production builds
- If you are using conda or mamba (replace command accordingly):
  - conda env create -f ./.ci_scripts/environment.yml
  - conda activate conda-forge-docs
  - For live builds, npm install && npm run start
  - For production builds, run .ci_scripts/update_docs
Make and commit your changes.
Submit a pull request to the main repository proposing your changes.

Code of conduct

We at conda-forge adhere to the NumFOCUS Code of Conduct:

Be kind to others. Do not insult or put down others. Behave professionally. Remember that harassment and sexist, racist, or exclusionary jokes are not appropriate for conda-forge.

All communication should be appropriate for a professional audience, including people of many different backgrounds. Sexual language and imagery is not appropriate.

conda-forge is dedicated to providing a harassment-free community for everyone, regardless of gender, sexual orientation, gender identity and expression, disability, physical appearance, body size, race, or religion. We do not tolerate harassment of community members in any form.

Thank you for helping make this a welcoming, friendly community for all.

Reporting guidelines

If you believe someone is violating the code of conduct, please report this in a timely manner. Code of conduct violations reduce the value of the community for everyone. The team at conda-forge takes reports of misconduct very seriously and is committed to preserving and maintaining the welcoming nature of our community.

Reports should be sent to [email protected], a private mailing list only accessible by the members of the core team. If your report involves a member of the core team, please send it to NumFOCUS following these instructions.

All reports will be kept confidential. Please have a look at the Reporting guidelines.

Enforcement: What happens after a report is filed?

conda-forge's team and/or our event staff will try to ensure your safety and help with any immediate needs, particularly at an in-person event. Once we have received the report through the relevant authorities, conda-forge will make every effort to acknowledge the receipt and take action. Have a look at the process of What Happens After a Report is Filed?.

conda-forge meetings

Refer to our Community > Meeting minutes page.

File: docs/maintainer/understanding_conda_forge/feedstocks.md

The feedstock

A feedstock is the home of one recipe; it may produce more than one conda artifact in the case of a multi-output recipe.
The feedstock is where for most events in the life of a recipe take place.

Initialization

The feedstock repository is created following the merging in staged-recipes (see Feedstock creation for details on that process).

Package building diagram

Package building can be triggered by several events, which are described in the next section.
In all of those cases, the following sequence plays out.

mermaid

sequenceDiagram
    box github
    participant f as feedstock
    end
    box CI provider
    participant c as CI
    end
    box distribution infrastructure
    participant s as cf-staging channel
    participant cf as conda-forge channel
    participant cdn as CDN
    end
    f->>+c: trigger build
    Note right of c: 1. build2. local validate
    opt if valid and required (4.)
    c->>s: upload packages
    s->>c: report reception success/failure
    Note right of s: 3. remote validate
    s->>cf: upload packages
    cf->>cdn: upload packages
    end
    c->>-f: report success/failure

:::note

For Linux and noarch packages, the build itself is carried out in a Docker container on the CI. On macOS and Windows, the CI runner system image is used after tuning it a bit.
The local validation happens on the CI and checks that the artifacts produced during the build are permissible for this feedstock by consulting the feedstock-outputs repository.
The server-side validation is essentially the same as 2. It is repeated inside the distribution infrastructure to guard against potential intentional or unintentional interference at the feedstock level, which is easier to access.
The upload is only triggered if the local validation (2.) was successful. Additionally, it is only performed under certain conditions, for example for commits in main, but not in PRs. Note that the package may also fail to transfer from cf-staging to conda-forge if the server-side validation (3.) fails. If 2. succeeds and 3. fails, this is usually due to an outdated token.

:::

Events that trigger new builds

Package building is either triggered as part of a PR or on commits to branches in the feedstock repository (which in turn usually stem from the merging of PRs).

:::warning
Any commit on any branch in the feedstock can lead to the building and publication of a package.
To avoid the gratuitous publication of improper packages, development branches MUST NOT be added to the feedstock repository.
Instead, they live in forks of the feedstock repository and the associated work is added only via pull requests.
:::

Almost all changes to the feedstock repository are performed via PRs.
This is true both for manual maintainer intervention and conda-forge automation.

:::info
It is possible to add commits to branches directly.
This is occasionally used to re-trigger a failed CI run with an empty commit:

console

git commit --allow-empty -m "Retrigger CI"

:::

Manually submitted PRs

These PRs are not automated. Any Github user can open a new PR by forking the feedstock, creating a fresh branch from main and adding the necessary commits to achieve the intended change (e.g. building a new version or adding a new platform).

It is up to the feedstock maintainers and/or the conda-forge/core team to review, approve and merge the PR, or to reject it and close it.

During the lifetime of the PR, some automated operations will take place:

The linter will scan the state of the recipe to require changes and suggest improvements. If not fulfilled, this will result in a failed CI run. Linter failures must not be ignored without explicit core approval.
The PR template will ask you to rerender the feedstock at least once per PR. This will ensure that the CI configuration is up-to-date, among other things. You can use the bot command @conda-forge-admin, please rerender in any comment, or do it locally via conda-smithy rerender.

Automated PRs

There is a variety of situations in which the conda-forge automation will create PRs.
In these cases, it is generally the privilege of the feedstock maintainers to review and merge the PR, triggering the action on the repository.

Every commit on a branch will trigger the ci unless its commit message contains the tag [ci skip], which can be achieved for PRs by including it in the PR title. Some providers ignore this tag during PRs but do obey it in runs triggered by a branch like main.

Version updates

When a new version is released upstream, a PR needs to be created that performs the necessary updates to the feedstock.
At a minimum, that includes updating the version, download URL, and hash of the upstream source artifact.
In addition, other changes to the recipe may be needed, such as updated dependency requirements, a change to the noarch status of the package, or an adaptation of the build or test scripts.
While these last changes often need to be done by the maintainers, conda-forge has sophisticated capabilities to add the initial version update PR.

:::info How does it work?

This happens in two steps in the CI of conda-forge-bot.

First, the version information is updated from upstream sources and stored in the conda-forge-bot-data repo, more specifically in the versions directory tree, nested by hash with one file per package.

mermaid

sequenceDiagram
    participant cfs as conda-forge-bot
    participant gha as github actions
    participant cft as conda_forge_tick
    participant ups as upstream
    participant cfg as conda-forge-bot-data
    loop every hour at :15, :45
        cfs->>gha: bot-versions
        gha->>cft: update-upstream-versions
        cft->>cfg: load package information from `graph.json`
        loop for every package
            cft->>ups: query version
            ups->>cft: return version
            cft->>cfg: write new version
        end
    end

Second, the main bot CI job, the bot-bot action in conda-forge-bot creates PRs for all packages that have a new version available upstream.
Here is a simplified diagram of how that is done. For the full picture, read below.

mermaid

sequenceDiagram
    participant cfs as conda-forge-bot
    participant gha as github actions
    participant cft as conda_forge_tick
    participant fs as feedstock
    participant cfg as conda-forge-bot-data
    loop self renewing
        cfs->>gha: bot-bot
        gha->>cft: auto-tick
        note right of cfg: the graph now containsthe new version information
        cft->>cfg: load package information from `graph.json`
        loop for every package
            opt if new version
                cft->>fs: rewrite recipe and open pr
            end
        end
        gha->>gha: re-trigger bot-bot
    end

:::

Once submitted, it is up to the feedstock maintainers to check the PR, make any necessary adjustments, and merge it into the feedstock branch.

This version update is an example of a migrator. Read more about migrators in the following section.

Rebuilds for migrators

The version update is one example of a migrator.
In reality, there are more occasions and reasons to update recipes, for example, to recompile an otherwise unchanged binary program or library to link against a newer version of a dependency or to add support for a new architecture.
This kind of use case is handled by migrators, which are a general recipe rewriting tool.

A more complete picture of what auto-tick does is the following:

mermaid

sequenceDiagram
    participant cfs as conda-forge-bot
    participant gha as github actions
    participant cft as conda_forge_tick
    participant fs as feedstock
    participant cfg as conda-forge-bot-data
    loop self renewing
        cfs->>gha: bot-bot
        gha->>cft: auto-tick
        note right of cfg: the graph now containsthe new version information
        cft->>cfg: load package information from `graph.json`
        loop for every migrator
            create participant mg as migrator
            cft->>mg: run migrator on graph
            note right of mg: 1. filter applicable package to produce effective graph2. determine migration order3. run migrator on every possible node
            destroy mg
            mg->>fs: create migration PR
        end
        gha->>cfs: deploy, i.e. commit changed pr information
        gha->>gha: re-trigger bot-bot
    end

Migrators are a powerful mechanism that can do almost arbitrary recipe changes.
They are written in Python and the current set of migrators can be found in the conda-forge/conda-forge-bot repository.

File: docs/maintainer/understanding_conda_forge/index.mdx

title: 'Understanding conda-forge'

Understanding conda-forge

import DocCardList from '@theme/DocCardList';

File: docs/maintainer/understanding_conda_forge/life_cycle.md

The life cycle of a package

conda-forge implements a particular workflow for building, publishing and maintaining conda packages.
However, the core concepts are the same for any conda packaging solution.

General concepts about conda packaging

conda packages are built off conda recipes, which consist of a metadata file (like meta.yaml or recipe.yaml), and optionally supporting scripts and data.
A build tool (usually conda-build or rattler-build) takes the recipe and produces one or more packages (also referred to as outputs and/or artifacts, depending on the context).

While you can distribute the artifacts on your own, the conda packages are usually uploaded to a conda channel hosted in a server like Anaconda.org.
This channel server processes all uploaded packages and aggregates the metadata contained in the packages in a single repodata.json file per platform or subdir.
For example, this is a subset of the conda-forge repodata for Linux x64 systems: current_repodata.json.

These are the metadata files that the conda client fetches when the user types conda install ... or similar commands.
The solver will process all the metadata and will provide the most adequate selection of packages to the user, which are then downloaded, extracted and linked into the target conda environment.

Post-publication particularities

For most packages, the paragraphs above are enough to describe their life cycle.
However, the repodata-first approach followed in the conda ecosystem allows for some unique features in the post-publication stages.

For large volume channels like conda-forge, Anaconda.org delivers the artifacts through a CDN network for faster access.
The CDN network is synced with the channels periodically.
As a result, packages take around 15 minutes to be available for installation after their publication.

This repodata-first approach offers a unique opportunity to post-process the repodata files.
This way, we can fix metadata issues without rebuilding packages.
Note that these changes do not propagate back to the metadata contained in the packages.

Anaconda.org also offers the concept of channel labels, which in practice
behave as subchannels. The default label is main. When a new label is added, the package is
also visible in the subchannel <channel>/label/<label>. For example, a package uploaded to
conda-forge and labeled as test and main will be available in the conda-forge channel, but
also in the conda-forge/label/test subchannel.

The life cycle on conda-forge

Anyone can run conda-build on their computer and manually upload their packages to Anaconda.org.
However, that approach has a few problems:

It doesn't facilitate collaboration.
There's no transparency in the process.
Reproducibility is system-dependent.
Compatibility across packages is not guaranteed.
It doesn't scale well beyond a handful of packages.

On conda-forge, most packages are built using public CI services and maintained by thousands of volunteers, which requires approaching the problem in a different way to guarantee fine-grained control of permissions, independent project management, and automated batch updates.

The main idea is that each conda recipe is processed by a separate GitHub repository.
These repositories, named feedstocks in conda-forge, host the user-contributed conda recipe plus several auto-generated required scripts, configuration files, and CI pipelines to build and export the conda artifacts.
Under this setup, the conda-forge bots can traverse the conda-forge repositories to re-generate and update feedstocks as needed when a global change or fix needs to be issued.

To be given a conda-forge feedstock, contributors must first submit their recipe for review to the staged-recipes repository.
Once reviewed and approved, the PR is merged to main, which triggers the feedstock creation.

After accepting the invitations to the conda-forge organization, the submitting contributor(s) will have been given commit rights to that repository.
By then, the feedstock creation machinery will have registered the new repository with the required CI services and populated its contents with the submitted recipe, plus the supporting scripts, configuration files and CI pipelines.

These pipelines will process the initial commits to produce and upload the conda artifacts to the cf-staging channel.
Any subsequent pushes to main (e.g. merged PRs) or other enabled branches will undergo the same process.

:::info
For existing feedstocks, conda-forge bots will often send automated PRs for new project releases or maintenance tasks.
You can find more details about it in Automation & bots.
:::

The validation server will detect the new uploads on cf-staging and will perform some checks on those artifacts.
If successful, the artifacts will then be copied to the actual conda-forge channel.

At this point, the channel server will process the contents of the new packages to retrieve their metadata and update the repodata files.
On the next CDN sync cycle, the artifacts will be distributed to the delivery network for faster access.
Validation and CDN sync usually take around 15 minutes after the CI is passing on main.
From this moment on, users can install the new packages from the CLI.

Post-publication particularities

In an ideal world, that would be the end of the life cycle. However, in some cases, some packages go through some post-publication stages.

If the package metadata is found to be wrong or out-of-date, it can be modified without rebuilding the package.
The channel server can apply patches to the repodata files directly, via instructions published in conda-forge-repodata-patches that are processed weekly.

Sometimes, there are issues with a published package that cannot be amended with a repodata patch (e.g. libraries were built wrong and segfault).
In these cases, the packages can be retired by labeling them as broken.
This is done through the admin-requests repository.
As part of the CDN-driven metadata patching, packages labeled as broken are not included in the final repodata index.
However, they are still available via direct URL access.
This allows organizations to retire packages from normal, solver-driven installs without compromising the reproducibility offered by lock files.

Finally, a project might have reached a status where no further updates are needed or expected (e.g. it has been superseded by a new project).
If the maintainers want to, these feedstocks can be archived and marked as read-only, which is also done via admin-requests.

Summary of stages

These stages are key concepts in the conda-forge documentation.
Feel free to refer to this list at any time as you check the rest of the documentation.

Initial submission to staged-recipes
Feedstock changes:
- A. Repository initialization
- B. Automated maintenance updates
- C. PRs submitted by users
Package building
Package validation
Package publication
Post-publication:
- A. Repodata patch
- B. Mark a package as broken
- C. Archive the feedstock

:::info
If you want to read more about the infrastructure details behind these stages,
consider reading our Infrastructure guide.
:::

File: docs/maintainer/understanding_conda_forge/staged_recipes.md

Staged-recipes

staged-recipes is the gateway to conda-forge.
Every package published has gone through this repository as part of the submission process.

Submission to staged-recipes

Users normally follow these steps:

Fork the conda-forge/staged-recipes repository and create a new branch from main.
Add a meta.yaml or recipe.yaml file (plus other files as needed) in a new subdirectory under recipes/.
Open a new pull request and pass the CI checks, which include building the recipe under different operating systems and some static analysis of the recipe files (linting).
Ask for a review and apply the suggestions.

When the PR is approved and merged to main, the new directory under recipes/ will trigger the staged-recipes pipelines, which will create a new feedstock with the recipe contents.

mermaid

sequenceDiagram
    actor c as contributor
    participant repo as staged-recipes repo
    rect var(--ifm-color-primary-contrast-background)
        Note right of c: 1: Prepare PR
        c->>repo: submit PR
        activate repo
        loop
            repo->>c: report failing CI
            deactivate repo
            c->>repo: add commits
            activate repo
        end
        repo->>c: report successful CI
        deactivate repo
    end
    rect var(--ifm-color-primary-contrast-background)
        Note right of c: 2: Solicit and address reviews
        loop
            c->>repo: mark as ready for review
            create actor reviewer
            repo->>reviewer: request review
            reviewer->>repo: provide comments
            c->>repo: address comments
            activate repo
            loop
                repo->>c: report failing CI
                deactivate repo
                c->>repo: add commits
                activate repo
            end
            repo->>c: report successful CI
            deactivate repo
        end
    end
    rect var(--ifm-color-primary-contrast-background)
        Note right of repo: Integrate new package into conda-forge
        reviewer->>repo: accept PR
        reviewer->>repo: merge PR
    end

Feedstock creation

Once a new recipe has been merged into staged-recipes, it will be converted to a feedstock.
This creates the home of the recipe as a new repository under the conda-forge organization.
It also creates the associated team and registers the recipe with the CI providers that are used for building packages, as well as with the distribution infrastructure to allow for uploads.

mermaid

sequenceDiagram
    participant sr as staged-recipes repo
    participant ar as admin-requests repo
    loop Several times per hour
        ar->>sr: check for new recipes
        loop for every new recipe
            create participant cs as conda-smithy
            ar->>cs: register github
            create participant fs as feedstock repo
            participant cf as conda-forge organization
            participant ci as ci providers
            cs->>fs: create feedstock repo
            cs->>cf: create maintainers team
            cs->>fs: add maintainers team
            ar->>cs: register ci
            cs->>ci: register builds
            destroy cs
            cs->>ar: finish
            ar->>sr: remove recipe from staged-recipes
        end
    end

Once the feedstock creation is completed successfully, all future events are handled through the feedstock;
the staged-recipes repository no longer plays a role.

File: docs/maintainer/conda_forge_yml.mdx

title: 'Configuring your feedstock'

Configuring your feedstock

import CondaForgeYmlSchema from '@site/src/components/CondaForgeYmlSchema';

You can configure how your feedstock is set up and built via the conda-forge.yml file that is present in its root directory.
Additionally, a small subset of options are configured in recipe/conda_build_config.yaml.

Rerendering the feedstock after you modify this file is usually required and always a good idea (see Rerendering feedstocks).

recipe/conda_build_config.yaml

While most settings are configured via conda-forge.yml,
some settings are defined in recipe/conda_build_config.yaml.
Unlike the former, this file can take advantage of selectors to match specific job configurations (e.g. CPU vs. GPU jobs).

Note that conda_build_config.yaml conventions specify that all values must be a list of strings, even if they only take one item.
Multiple items are often only needed when filtering conditions with selectors.

channel_sources

Each item must be a comma-separated list of channels to use to install dependencies for the recipe.
Only conda-forge and its labels are supported.

Example:

yaml title="recipe/conda_build_config.yaml"

channel_sources:
  - conda-forge/label/A_rc,conda-forge

Search query for real-world examples.

channel_targets

The channel where the packages will be uploaded to, expressed as a space-separated channel label pair.
Defaults to ["conda-forge main"].

You only need to define this if you need to upload packages to a different label (e.g. RCs).

Example:

yaml title="recipe/conda_build_config.yaml"

channel_targets:
  - conda-forge A_rc

Search query for real-world examples

github_actions_labels

Defines the value that will populate the runs-on field on Github Actions build workflows (e.g. ubuntu-latest).

You can use it to configure custom runners on self-hosted infrastructure, or override the default Github-hosted runner / VM image.
Refer to conda-forge/admin-requests for possible values.

Each string must be one of:

A non-empty string that will be taken as is for the runs-on field(s) matching the selector for the respective item.
Use this to configure self-hosted runners as needed. If the string contains the substring gpu,
it may enable special behaviour on that platform (e.g. Docker GPU passthrough arguments).
A non-empty string that starts with self-hosted@ will be dealt with in the same way, but:
- The self-hosted@ prefix will be removed.
- Generic self-hosted labels will be appended to runs-on.
  This is needed in some providers that expect additional labels like self-hosted and Linux.
  Other providers either don't need it, or fail with these labels.
If absent or set to default, runs-on will use the pre-configured Github-hosted runner (e.g. ubuntu-latest for Linux x64).

Example:

recipe title="recipe/conda_build_config.yaml"

github_actions_labels:
- a-custom-self-hosted-provider  # [linux64]
# absent value for linux-aarch64 means it will use the default; same as:
# - default  # [linux and aarch64]

Search query for real-world examples

conda-forge.yml schema

File: docs/maintainer/guidelines.md

title: 'Guidelines'

Guidelines

Transferring to conda-forge

This document intends to layout some guidelines on the transfer of
conda-recipes and
anaconda-recipes
to conda-forge. These aren't hard and fast rules, instead are open to reasonable
interpretation and reviewer's judgement.

It is anticipated that almost all recipes from those repos shall be
proposed for addition here, though it may be decided that a few don't
actually belong or should not be supported anymore.

While adding a package from either location, inspect the commit history
to see who had made changes to the recipe in the past. Anyone who has
touched the recipe should be pinged about it, so that they can be added here. They
should also be consulted with regards, if the recipe needs any
tweaks before being added. Also, they should be asked if they would
like to be added as maintainers. If they give their consent
to take up the role as a maintainer, only then they should be added in the maintainer list.

In all cases while porting a recipe, you should add yourself as a
maintainer. Some contributors to these repos might be quite prolific, but may
not be as actively engaged. If they specify they only want to be contacted
for certain recipes or none at all, please respect their wishes and add them too.
Make note of what recipes (if any) they would like to be notified for. If
they are no longer interested in any conda recipes, make that note here
as well. Before contacting anyone, please consult the list in this
issue
to see if that contributor has restrictions.

While porting make sure the recipe follows the linting specifications.
The section order should go package, source, build,
requirements, test, about, extra/recipe-maintainers. It
is recommended to add a build section with the number set to
0 explicitly even if the rest is unneeded. If there is no build for
Windows, make sure to add skip: true # [win] to the build
section. The about section must have the home URL (verify if the
URL is still correct), license (verify if the correct license is present),
and a one sentence (or few words) summary. When specifying the version, it
is strongly recommended that jinja templating be used to set the version
at the top (e.g. {% set version = "0.10.1" %}) and then replace all
uses of the version with {{ version }}. Preference should be given to
compressed source balls as opposed to version control checkouts. Make sure
all links to compressed source balls allow for easy changing of the version
(using latest is not acceptable). Also, a checksum should be included with
all compressed source balls to allow for verification of downloads.

It is required to add tests with all packages. These can include, but are
not limited to, checking if libraries are installed, python imports, simple
code snippet to compile or run a basic test, command line usage (checking
help or version). It is suggested to get the compiled code to run all tests (e.g.
make check) to ensure it was built properly. This normally should
happen in the build.

It is possible, though not recommended, to include multiple recipes into a
single pull request on staged-recipes. conda-build-all is used to determine
the build order and the necessary build matrix (e.g. which python versions to
build against). From a practical perspective, there are limitations on the
continuous integration resources and also on what reviewers are able/willing
to review in a single pull request.
A large pull request with numerous recipes makes it more difficult to review.
If the recipes make it through these two constraints and are merged, race
conditions amongst the different feedstocks may require work by you and/or
core maintainers to restart them in such a way to build everything in a
suitable order.
None of this is to say that one can't add multiple recipes in a single
pull request. One certainly can do this and it can work, but the
recommendation is to open a PR with one recipe first, and to ping
@conda-forge/core to ask for agreement about adding one or two additional
recipes.

Intended Usage

Maintainers' time and CI resources are what enable conda-forge. They are just as scarce as valuable. conda-forge has enough capacity to support releasing packages, but not developing them.

Publishing a package to conda-forge signals it is suitable for users not involved with development. However, publishing does not always happen error-free. Multiple commits are acceptable when debugging issues with the release process itself.

Fortunately, there are options for optimizing the development of a package.

conda-smithy is a tool used by conda-forge itself to manage feedstocks. conda-smithy can be used to create an internal development feedstock that is separate from conda-forge.
ci-helpers is a set of scripts that drive various CI services using environment variables.

Renaming Packages

Sometimes, packages are misnamed.
To correct the name of the package, please submit a PR into staged-recipes with the correct name.
During the review process, please make certain to note that the package is renamed and contact a member of conda-forge/core to remove the old feedstock (and potentially package, if needed).

Occasionally, the .gitmodules file in the feedstocks needs to be updated to remove the old feedstock.
It's not entirely clear what those circumstances are.
See conda-forge.github.io#1070.

If an existing feedstock has already created a package of the same name,
then you may need to add the new feedstock to the feedstock-outputs map.

Fixing Broken Packages

Sometimes, you need to remove a package from the conda-forge channel on Anaconda.org.
There can be many reasons for this, but the ones that immediately come to mind are:

Incorrect pinnings or metadata
Packages being renamed
Broken package contents

We prefer to not remove packages for the following reasons:

Unaffected users are unable to get the broken package.
Unable to reverse (what if we were incorrect to remove it).
Loss of reproducibility (unable to create an old environment).
Not as community friendly (leaves no opportunity to review decision).
Blocks anyone from inspecting the broken packages.

Instead, if possible, we prefer to take one of the following actions:

If the only issue is in the package metadata, we can directly patch it using
the repo data patches feedstock.
To change the repo data for your package, make a PR on the feedstock.
If the the package contents themselves are broken, we add an extra label broken
to the package. Packages with this extra label are removed from the repo data on the
main label. Thus they are not considered by the solver
but their binaries are still available on Anaconda.org. To get the broken label
added to your package, please refer to Removing broken packages.

Adding the broken label to a package is more destructive than patching the repo data
and thus we prefer repo data patches over labeling things as broken.

Becoming a maintainer

conda-forge is a community project and it can therefore happen that feedstocks become temporarily abandoned.
You can join the maintainer team of a feedstock by adding your github-id to the recipe-maintainers section in the recipe's meta.yaml.
Please refer to Updating the maintainer list for detailed instructions.

Language versions

conda-forge contains packages from a number of languages including Python and R, among many others.
Each of these language-specific packaging sub-ecosystems needs to keep cadence with the language itself, making it challenging to have a blanket policy for how long to keep older versions of the language around.
As it comes up, each group should be able to define their own policy on how long to keep older versions of their language around.

Python

For the Python language, conda-forge aims to keep package builds active and available for all the Python versions currently supported upstream.
However, the support for the oldest 3.{n} version may be disabled a few months before it reaches its end-of-life, once migration for the 3.{n+5}rc starts.
Whenever Python 4.0 comes out we'll need to figure out if this policy should change to support multiple versions of 3.x and 4.x simultaneously.
Fortunately, we can punt on that for now.
The current de facto policy can be found in python-feedstock#794.

Reviewing recipes

To add new packages to conda-forge, users can submit a PR to staged-recipes (see Contributing packages for more details),
where it will undergo a series of automated checks and a code review.
Any conda-forge member can perform a code review, but the final merge can only be done by the staged-recipes or core teams.
The following sections suggest guidelines on how to perform a successful code review.
We distinguish between "Required" and "Recommended" as follows:

Required: These guidelines are very important and a requisite for PR acceptance. Exceptions are rare and usually require core approval.
Recommended: These are considered "nice to have" features. Ideally, all recipes should abide by them, but exceptions are tolerated as long as justifiable reasons are provided.

Generalities

Required:

All interactions in the review adhere to our Code of Conduct.
conda-forge-linter checks pass successfully.
Sometimes the linter will also suggest modifications considered optional (hints); even if recommended, these are not required to accept the submission.
The CI checks pass successfully in the required platforms. Exceptions:
- noarch: python can fail in platforms other than Linux (e.g. missing dependency). For non-noarch packages, the failing platform should be skipped via skip: true # []
- CI times out or runs out of storage because it tries to build all Python versions in the same job. As long as one version passes, that's ok, since they will run individually in the resulting feedstock.
The submission fulfills the pull request template checklist.
The license has been correctly identified and allows redistribution.
The source should not contain vendored code. If it does:
- Package the vendored project separately and specify the needed dependency in the requirements section. Preferred if the vendored code is needed at runtime.
- Allow the vendored code, but make sure the license files are included in the about.license field. Usually ok if it's only a build-time dependency (e.g. headers-only library)

Recommended:

Source should be obtained from a URL that provides a stable tarball (same SHA over time).
Git or other SVC repositories should only be used as a last resort.
Host requirements contained in the conda-forge pinnings should be name-only; i.e. they do not specify a separate version.
Runtime requirements are not pinned too strictly without justification.
Thanks to repodata patches, we can afford to be optimistic about lower or upper bounds instead of single-version pins: >=1.4.2,<1.5 is better than ==1.4.2.
The package should place its files under standard locations (e.g. executables under $PREFIX/bin), unless justification is provided.

Python-specific details

Required:

noarch: python packages fulfill the required criteria to be considered as such.

Recommended:

The package does not accidentally include a tests (also test, _tests, or similar) top-level package.
The list of files is usually printed by pip install after the adding license file message.
If this happens, upstream should modify their setuptools.find_packages() usage accordingly.
Alternatively, a patch can be applied. See example.
The modules checked by test.imports are not empty (this can happen with placeholder __init__.py files in top-level packages).
The versions reported by pip list and conda build logs match.
pip check passes. See pip check for more details.
If a project can be considered noarch (see criteria), it should be packaged as such.

Compiled objects

Required:

The source does not include compiled files.
In principle, all compiled objects need to be generated in the conda-forge CI, from source.
Exceptions to this rule (e.g. binary repackaging) need to be approved explicitly.

Recommended:

SONAMEs follow naming recommendations given by upstream.
If ABI compatibility is important for the package, run_exports are set accordingly.
See Pinned dependencies and the conda-build docs for more information.

File: docs/maintainer/index.mdx

title: 'Maintainer Documentation'

Maintainer Documentation

import DocCardList from '@theme/DocCardList';

1. Project Overview & Quickstart (conda-forge/LICENSE) Copy Chapter

LICENSE

Repository Details Copy Section

2. Official Technical Reference & Guides (conda-forge/conda-forge.github.io) Copy Chapter

File: README.md Copy Chapter

[conda-forge.org](https://conda-forge.org)

Overview Copy Chapter

Improving the docs Copy Chapter

Code of conduct Copy Chapter

Reporting guidelines Copy Section

Enforcement: What happens after a report is filed? Copy Section

conda-forge meetings Copy Chapter

File: docs/maintainer/understanding_conda_forge/feedstocks.md Copy Chapter

The feedstock

Initialization Copy Chapter

Package building diagram Copy Chapter

Events that trigger new builds Copy Chapter

Manually submitted PRs Copy Section

Automated PRs Copy Section

Version updates

Rebuilds for migrators

File: docs/maintainer/understanding_conda_forge/index.mdx Copy Chapter

title: 'Understanding conda-forge' Copy Chapter

Understanding conda-forge

File: docs/maintainer/understanding_conda_forge/life_cycle.md Copy Chapter

sidebar_position: 1 Copy Chapter

The life cycle of a package

General concepts about conda packaging Copy Chapter

Post-publication particularities Copy Section

The life cycle on conda-forge Copy Chapter

Post-publication particularities Copy Section

Summary of stages Copy Chapter

File: docs/maintainer/understanding_conda_forge/staged_recipes.md Copy Chapter

Staged-recipes

Submission to staged-recipes Copy Chapter

Feedstock creation Copy Chapter

File: docs/maintainer/conda_forge_yml.mdx Copy Chapter

title: 'Configuring your feedstock' Copy Chapter

Configuring your feedstock

recipe/conda_build_config.yaml Copy Chapter

channel_sources Copy Section

channel_targets Copy Section

github_actions_labels Copy Section

conda-forge.yml schema Copy Chapter

File: docs/maintainer/guidelines.md Copy Chapter

title: 'Guidelines' Copy Chapter

Guidelines

Transferring to conda-forge Copy Chapter

Intended Usage Copy Chapter

Renaming Packages Copy Chapter

Fixing Broken Packages Copy Chapter

Becoming a maintainer Copy Chapter

Language versions Copy Chapter

Python Copy Section

Reviewing recipes Copy Chapter

Generalities Copy Section

Python-specific details Copy Section

Compiled objects Copy Section

File: docs/maintainer/index.mdx Copy Chapter

title: 'Maintainer Documentation' Copy Chapter

Maintainer Documentation

Explore Related Technologies & Topics

1. Project Overview & Quickstart (conda-forge/LICENSE)

Repository Details

2. Official Technical Reference & Guides (conda-forge/conda-forge.github.io)

File: README.md

Overview

Improving the docs

Code of conduct

Reporting guidelines

Enforcement: What happens after a report is filed?

conda-forge meetings

File: docs/maintainer/understanding_conda_forge/feedstocks.md

Initialization

Package building diagram

Events that trigger new builds

Manually submitted PRs

Automated PRs

File: docs/maintainer/understanding_conda_forge/index.mdx

title: 'Understanding conda-forge'

File: docs/maintainer/understanding_conda_forge/life_cycle.md

sidebar_position: 1

General concepts about conda packaging

Post-publication particularities

The life cycle on conda-forge

Post-publication particularities

Summary of stages

File: docs/maintainer/understanding_conda_forge/staged_recipes.md

Submission to staged-recipes

Feedstock creation

File: docs/maintainer/conda_forge_yml.mdx

title: 'Configuring your feedstock'

recipe/conda_build_config.yaml

channel_sources

channel_targets

github_actions_labels

conda-forge.yml schema

File: docs/maintainer/guidelines.md

title: 'Guidelines'

Transferring to conda-forge

Intended Usage

Renaming Packages

Fixing Broken Packages

Becoming a maintainer

Language versions

Python

Reviewing recipes

Generalities

Python-specific details

Compiled objects

File: docs/maintainer/index.mdx

title: 'Maintainer Documentation'