docs(contributing): switch to rattler-build on Contributing packages page

lucascolley · lucascolley · commit be47d720bd78 · 2025-07-07T15:05:14.000+01:00
diff --git a/blog/2020-02-04-gsoc.md b/blog/2020-02-04-gsoc.md
@@ -33,7 +33,6 @@ detailed listing of the issues that need work.
     We have a large backlog of maintenance and refactoring issues that
     are great for people with a range of experience from beginners to
     true code ninjas.
-
     - Integration Testing for the Autotick Bot
 
       > Run true integration testing on a copy of the graph to better
diff --git a/docs/maintainer/adding_pkgs.md b/docs/maintainer/adding_pkgs.md
@@ -41,33 +41,29 @@ The staging process i.e adding a package's recipe has three steps:
 
 ### Generating the recipe
 
-There are, currently, three ways to generate a recipe:
-
-1. If it is an R package from [CRAN](https://cran.r-project.org/), kindly
-   start by using the [conda-forge helper script for R recipes](https://github.com/bgruening/conda_r_skeleton_helper) instead.
+1. If it is an R package from [CRAN](https://cran.r-project.org/), a Python package from [PyPI](https://pypi.org),
+   a Perl package from [CPAN](https://www.cpan.org), or a Lua package from [Luarocks](https://luarocks.org),
+   generate a recipe with `rattler-build generate-recipe`.
    Then if necessary, you can make manual edits to the recipe.
-2. If it is a python package, you can generate the recipe as a starting point with `grayskull`.
 
    :::note
 
-   [Grayskull](https://github.com/conda-incubator/grayskull) is an automatic conda recipe generator. The goal of this project is to generate concise recipes
-   for conda-forge and eventually replace conda skeleton. Presently, Grayskull can generate recipes for Python packages available on PyPI and also those not published on PyPI and only available as GitHub repositories.
-
-   Installation and usage of `grayskull`:
+   Installation and usage of `rattler-build`:
+   - [Install Pixi](https://pixi.sh/latest/installation/).
 
-   - Create a new environment using : `conda create --name MY_ENV`. Replace `MY_ENV` with the environment name.
-   - Activate this new environment : `conda activate MY_ENV`.
-   - Run `conda install -c conda-forge grayskull` to install `grayskull`.
-   - Followed by `grayskull pypi --strict-conda-forge YOUR_PACKAGE_NAME` to generate the recipe. Replace `YOUR_PACKAGE_NAME` with the package name.
+   - `pixi exec rattler-build generate-recipe INDEX_NAME PACKAGE_NAME`.
+     Replace `INDEX_NAME` with the name of the index (e.g. `cran`) and `PACKAGE_NAME` with the name of the package.
 
    :::
 
-   You do _not_ necessarily have to use `grayskull`, and the recipes produced by `grayskull` might need to be reviewed and edited.
-   Read more about `grayskull` and how to use it [here](https://github.com/conda-incubator/grayskull#introduction).
+   You do _not_ have to use `rattler-build`, and the recipes produced by `rattler-build` might need to be
+   reviewed and edited.
+   Read more in the [rattler-build recipe generation documentation](https://rattler.build/latest/recipe_generation/).
 
-3. If it's none of the above, generate a recipe with the help of [the example recipe](https://github.com/conda-forge/staged-recipes/tree/master/recipes/example) in the [staged-recipes repository](https://github.com/conda-forge/staged-recipes) and modify it as necessary.
+2. If it's none of the above, generate a recipe with the help of [the example recipe](https://github.com/conda-forge/staged-recipes/tree/main/recipes/example-v1/recipe.yaml) in the [staged-recipes repository](https://github.com/conda-forge/staged-recipes), and [the rattler-build documentation](https://rattler.build/latest/),
+   including [the full recipe specification](https://rattler.build/latest/reference/recipe_file/).
 
-Your final recipe should have no comments (unless they're actually relevant to the recipe, and not generic instruction comments), and follow the order in the example.
+Your final recipe should have no comments (unless they're actually relevant to the recipe, not just generic instruction comments), and follow the order in the example.
 
 :::note
 
@@ -90,20 +86,19 @@ In case you are building your first recipe using conda-forge, a step-by-step ins
 2. Fork and clone the [staged-recipes](https://github.com/conda-forge/staged-recipes)
    repository from GitHub.
 3. Checkout a new branch from the staged-recipes `main` branch.
-4. Through CLI, cd inside the ‘staged-recipes/recipes' directory.
+4. Through CLI, `cd` inside the `staged-recipes/recipes` directory.
 5. Within your forked copy, create a new folder in the recipes folder for your package (i.e, `...staged-recipes/recipes/<name-of-package>`)
-6. Copy [meta.yaml](https://github.com/conda-forge/staged-recipes/blob/master/recipes/example/meta.yaml) from the example directory.
-   All the changes in the following steps will happen in the COPIED meta.yaml (i.e., `...staged-recipes/recipes/<name-of-package>/meta.yaml`).
+6. Copy [`recipe.yaml`](https://github.com/conda-forge/staged-recipes/blob/main/recipes/example-v1/recipe.yaml) from the example directory.
+   All the changes in the following steps will happen in the COPIED recipe.yaml (i.e., `...staged-recipes/recipes/<name-of-package>/recipe.yaml`).
    Please leave the example directory unchanged!
-7. Modify the copied recipe (meta.yml) as needed. To see how to modify meta.yaml, take a look at
-   [The recipe meta.yaml](#id4).
+7. Modify the copied recipe (`recipe.yml`) as needed. To see how to modify `recipe.yaml`, take a look at
+   [the rattler-build documentation](https://rattler.build/latest/).
 8. Generate the SHA256 key for your source code archive, as described in the
-   example recipe using the `openssl` tool. As an alternative, you can also
-   go to the package description on [PyPi](https://pypi.org) from which you
-   can directly copy the SHA256.
+   example recipe using the `openssl` tool. Alternatively, for packages from [PyPI](https://pypi.org),
+   you can also go to the package description on PyPI, from which you can directly copy the SHA256.
 9. Be sure to fill in the `test` section. The simplest test will simply
    test that the module can be imported, as described in the example.
-10. Remove all irrelevant comments in the `meta.yaml` file.
+10. Remove all irrelevant comments in the `recipe.yaml` file.
 
 :::tip
 
@@ -120,10 +115,10 @@ curl -sL https://github.com/username/reponame/archive/vX.X.X.tar.gz | openssl sh
 #### Checklist
 
 - Ensure that the license and license family descriptors (optional) have the right case and that the license is correct. Note that case sensitive inputs are required (e.g. Apache-2.0 rather than APACHE 2.0). Using SPDX identifiers for license field is recommended. (see [SPDX Identifiers and Expressions](#spdx))
-- Ensure that you have included a license file if your license requires one – most do. (see [here](https://github.com/conda-forge/staged-recipes/blob/a504af81c05491bf7b0b018b2fa1efe64767985c/recipes/example/meta.yaml#L52-L55))
+- Ensure that you have included a license file if your license requires one – most do. (see [this section of the example recipe](https://github.com/conda-forge/staged-recipes/blob/3b151310e299162760033b9a165349fc255d28b7/recipes/example-v1/recipe.yaml#L88-L92))
 - In case your project has tests included, you need to decide if these tests should be executed while building the conda-forge feedstock.
 - Make sure that all tests pass successfully at least on your development machine.
-- Recommended: run the test locally on your source code to ensure the recipe works locally (see [Running tests locally for staged recipes](#staging-test-locally)).
+- Recommended: run the tests locally on your source code to ensure the recipe works locally (see [Running tests locally for staged recipes](#staging-test-locally)).
 - Make sure that your changes do not interfere with other recipes that are in the `recipes` folder (e.g. the `example` recipe).
 
 <a id="feedback-and-revision"></a>
@@ -150,7 +145,7 @@ If you have questions or have not heard back for a while, you can notify us by i
 
 - After the PR is merged, our [CI](../glossary.md#ci) services will create a new git repo automatically. For example, the recipe for a package named `pydstool` will be moved to a new repository [https://github.com/conda-forge/pydstool-feedstock](https://github.com/conda-forge/pydstool-feedstock). This process is automated through a CI job on the `conda-forge/staged-recipes` repo. It sometimes fails due to API rate limits and will automatically retry itself. If your feedstock has not been created after a day or so, please get in touch with the `conda-forge/core` team for help.
 - CI services will be enabled automatically and a build will be triggered automatically which will build the conda package and upload to [https://anaconda.org/conda-forge](https://anaconda.org/conda-forge)
-- If this is your first contribution, you will be added to the conda-forge [team](https://github.com/orgs/conda-forge/people) and given access to the CI services so that you can stop and restart builds. You will also be given commit rights to the new git repository.
+- If this is your first contribution, you will be added to the conda-forge [team](https://github.com/orgs/conda-forge/people) and be given access to the CI services so that you can stop and restart builds. You will also be given commit rights to the new git repository.
 - If you want to make a change to the recipe, send a [PR](../glossary.md#pr) to the git repository from a fork. Branches of the main repository are used for maintaining different versions only.
 
 <a id="feedstock-repository-structure"></a>
@@ -168,13 +163,13 @@ Each feedstock contains various files that are generated automatically using our
 
 #### recipe
 
-This folder contains the `meta.yaml` file and any other files/scripts needed to build the package.
+This folder contains the `recipe.yaml` file and any other files/scripts needed to build the package.
 
 <a id="license-txt"></a>
 
 #### LICENSE.txt
 
-This file is the license for the recipe itself. This license is different from the package license, which you define while submitting the package recipe using `license_file` in the `meta.yaml` file.
+This file is the license for the recipe itself. This license is different from the package license, which you define while submitting the package recipe using `license_file` in the `recipe.yaml` file.
 
 <a id="ci-files"></a>
 
@@ -207,7 +202,7 @@ The maintainer's job is to:
 
 ### Adding multiple packages at once
 
-If you would like to add more than one related packages, they can be added to
+If you would like to add multiple related packages, they can be added to
 staged-recipes in a single pull request (in separate directories). If the
 packages are interdependent (i.e. one package being added lists one or more of
 the other packages being added as a requirement), the build script will be able to
@@ -263,18 +258,17 @@ Once these steps are complete, you can continue with the steps in [Step-by-step
 
 <a id="id4"></a>
 
-<a id="the-recipe-meta-yaml"></a>
+<a id="the-recipe-yaml"></a>
 
-## The recipe meta.yaml
+## The `recipe.yaml`
 
-The `meta.yaml` file in the recipe directory is at the heart of every conda package.
+The `recipe.yaml` file in the recipe directory is at the heart of every conda package.
 It defines everything that is required to build and use the package.
 
-`meta.yaml` is in [yaml](https://en.wikipedia.org/wiki/YAML) format, augmented with [Jinja](http://jinja.pocoo.org/) templating.
-
-A full reference of the structure and fields of `meta.yaml` file can be found in the [Defining metadata (meta.yaml)](https://conda.io/projects/conda-build/en/stable/resources/define-metadata.html) section in the conda-build documentation.
+A full reference of the structure and fields of `recipe.yaml` file can be found in the
+[rattler-build recipe file documentation](https://rattler.build/latest/reference/recipe_file/).
 
-In the following, we highlight particularly important and conda-forge specific information and guidelines, ordered by section in `meta.yaml`.
+In the following, we highlight particularly important and conda-forge specific information and guidelines, ordered by section in `recipe.yaml`.
 
 <a id="meta-yaml-source"></a>
 
diff --git a/docs/maintainer/knowledge_base.md b/docs/maintainer/knowledge_base.md
@@ -1953,7 +1953,6 @@ There are two options for how to proceed:
 - Specify the environment variable `SETUPTOOLS_SCM_PRETEND_VERSION` with the version string.
   If specified this environment variable is the principle source for `setuptools_scm`.
   There are two ways how to do this:
-
   - If you are using build scripts, in `build.sh` specify:
 
     ```bash
diff --git a/docs/maintainer/updating_pkgs.md b/docs/maintainer/updating_pkgs.md
@@ -52,7 +52,6 @@ For these reasons, maintainers are asked to fork the feedstock to their personal
 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:
 
 1. Manually setting up git remotes:
-
    - Clone the conda-forge feedstock repository
    - Add the remote of the bot: `git remote add regro-cf-autotick-bot git@github.com:regro-cf-autotick-bot/<package>-feedstock.git`
      :::warning[Important]
@@ -98,15 +97,13 @@ Here we assume that you would like to update the feedstock `<feedstock>`. Feedst
 1. 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](https://github.com/conda-forge)/<feedstock> in your favorite web browser and click the `fork` button.
    - 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>`.
 
 2. Syncing your fork with conda-forge's 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 main branch: `git checkout main`
    - Register conda-forge's feedstock with `git remote add upstream https://github.com/conda-forge/<feedstock>`
    - Fetch the latest updates with `git fetch upstream`
@@ -115,7 +112,6 @@ Here we assume that you would like to update the feedstock `<feedstock>`. Feedst
 3. 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. `update_1_0_1`.
    - 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.
diff --git a/docs/user/transitioning_from_defaults.md b/docs/user/transitioning_from_defaults.md
@@ -74,7 +74,6 @@ are guidelines on how to go about this, while backing up your work and your envi
    to right click on the Anaconda / Miniconda installation folder. Check if you have
    created additional environments outside the installation root by running
    `conda info --envs`. Back those up too, if necessary.
-
    - Alternatively, you can also export lockfiles for all your environments, if preferred:
 
      ```shell
