Skip to content

Commit

Permalink
docs: add tutorials on Github workflow in FAQ
Browse files Browse the repository at this point in the history
  • Loading branch information
@bobleesj
bobleesj committed Dec 29, 2024
1 parent 48c6fe0 commit bd8cbf4
Show file tree
Hide file tree
Showing 6 changed files with 416 additions and 169 deletions.
122 changes: 78 additions & 44 deletions doc/source/conda-forge-guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,32 @@ How to release conda-forge package

.. _create-feedstock:

I already have a conda-forge feedstock. I want to release a new package version. How do I do that?
--------------------------------------------------------------------------------------------------

Please skip to :ref:`here <conda-forge-feedstock-release>`

I am new to conda-forge. How do I create a conda package?
---------------------------------------------------------

Here, you will learn how to release a conda package distributed through the conda-forge channel in 10 to 15 minutes. This guide assumes you are familiar with a basic clone, fork, and pull request (PR) workflow on GitHub.
Here, you will learn how to release a conda package distributed through the conda-forge channel in 10 to 15 minutes. This guide assumes you are familiar with a basic clone, fork, and pull request workflow on GitHub.

Overview
^^^^^^^^

The process is divided into three steps:


1. :ref:`Prepare recipe: <conda-forge-recipe-prepare>` You will learn to prepare package information in a file called ``meta.yaml`` using our group's cookiecutting template. The file serves as a recipe for building your conda package. The recipe contains the package version, the source code, the dependencies, the license, etc.

2. :ref:`Upload therecipe: <conda-forge-recipe-upload>` Once you have the ``meta.yaml`` generated, you will create a pull request the staged-recipe repository in the conda-forge repository `here <https://github.com/conda-forge/staged-recipes>`_

3. :ref:`Recipe review: <conda-forge-recipe-review>` One of the community members of conda-forge will review your ``meta.yaml`` and provide feedback. Once the recipe is approved, you will have a package available for ``conda install`` automatically, and you will have your own designated feedstock repository that contains ``meta.yaml`` in ``https://github.com/conda-forge/<package-name>-feedstock``.

Step 1. Prepare ``meta.yaml``. See Appendix 1 to learn more about ``meta.yaml``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _conda-forge-recipe-prepare:

1. Prepare conda package recipe in ``meta.yaml``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To generate a package, we first need to generate a "recipe" for the package. The recipe contains the type of programming language, the package version, the source code, the dependencies, and license, etc. This recipe is stored in a file called ``meta.yaml``.

Expand All @@ -24,42 +43,44 @@ If you are interested in learning more about each component within ``meta.yaml``

2. Answer the following questions. Default values in parentheses are used if no value is provided.

:github_org: The GitHub organization name. For example, ``diffpy``.
:github_org: The GitHub organization name. For example, ``diffpy``.

:repo_name: The name of the repository.
:repo_name: The name of the repository.

:module_name: The name of the module.
:module_name: The name of the module.

:version: The version of the package.
:version: The version of the package.

:Select: Choose PyPI. PyPI's ``sdist`` containing requirements files, src/tests, and ``pyproject.toml``
:Select: Choose PyPI. PyPI's ``sdist`` containing requirements files, src/tests, and ``pyproject.toml``

:project_short_description: A short description of the project
:short_description: A short description of the project

:project_full_description: A full description of the project
:full_description: A full description of the project

:license_file: The license file that is located in your project repository. i.g., ``LICENSE.rst``.
:license_file: The license file that is located in your project repository. i.g., ``LICENSE.rst``.

:recipe_maintainers: You may have multiple maintainers ``sbillinge, bobleesj`` or just ``sbillinge``
:maintainers: You may have multiple maintainers ``sbillinge, bobleesj`` or just ``sbillinge``

:build_requirements: copy ``requirements/build.txt`` from the project repo. It should be empty for pure Python packages, otherwise compilers will be required.
:build_requirements: copy ``requirements/build.txt`` from the project repo. It should be empty for pure Python packages, otherwise compilers will be required.

:host_requirements: Copy the following for the ``python >=3.11, setuptools, setuptools-git-versioning >=2.0, pip``. Copy ``requirements/host.txt``
:host_requirements: Copy the following for the ``python >=3.11, setuptools, setuptools-git-versioning >=2.0, pip``. Copy ``requirements/host.txt``

:runtime_requirements: copy ``requirements/conda.txt``:
:runtime_requirements: copy ``requirements/conda.txt``:

:testing_requirements: copy ``requirements/test.txt``
:testing_requirements: copy ``requirements/test.txt``

Now, you have ``recipes/<package-name>/meta.yaml`` generated.

Now, you have ``recipes/<package-name>/meta.yaml`` is generated.
.. important::
- For a pure python package, have you removed the ``build`` section under the ``requirements``? See https://github.com/conda-forge/diffpy.utils-feedstock/blob/main/recipe/meta.yaml for example.

- [ ] For a pure python package, have you removed the ``build`` section under the ``requirements``? See https://github.com/conda-forge/diffpy.utils-feedstock/blob/main/recipe/meta.yaml for example.
- Have you double-checked the license file name in ``meta.yaml`` against the license files in the project repository. If you are unsure, please confirm with the repository owner (Prof. Billinge).

- [ ] Have you double-checked the license file name in ``meta.yaml`` against the license files in the project repository. If you are unsure, please confirm with the repository owner (Prof. Billinge).

.. _conda-forge-recipe-upload:

Step 2. Upload ``meta.yaml``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2. Upload ``meta.yaml`` to conda-forge for initial review
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Fork https://github.com/conda-forge/staged-recipes and clone your forked repository

Expand All @@ -81,53 +102,58 @@ Step 2. Upload ``meta.yaml``

10. After the CI passes, create a new comment: ``@conda-forge/help-python Hello Team, ready for review!``

Step 3. Wait for review and merge
.. _conda-forge-recipe-review:


3. Wait for recipe review
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Wait for a ``conda-forge`` volunteer reviewer to review your submission. It may take up to one week.

2. Once the PR is merged by the reviewer (1) your package is available on conda-forge, and (2) a new repository will be created under https://github.com/conda-forge/package-name-feedstock/. Example: https://github.com/conda-forge/diffpy.structure-feedstock.


I already have a conda package. How do I distribute a new package version?
--------------------------------------------------------------------------
.. _conda-forge-feedstock-release:

Use the conda-forge feedstock to release a new version
------------------------------------------------------

This step assumes there is a new version of Python package released to PyPI. We will use that PyPI source code to generate a new conda package.
We release a new package once we have the ``version`` and ``SHA256`` sections in ``meta.yaml`` in ``https://github.com/conda-forge/<package-name>-feedstock`` located in the ``main`` branch. The conda-forge team asks to only modify ``meta.yaml``.

Obtain the ``SHA256`` value from `pypi.org <http://pypi.org>`_:
First, we will attain th ``SHA256`` value from `pypi.org <http://pypi.org>`_:

1. Visit the project on PyPI at ``https://pypi.org/project/<package-name>``
#. Visit the project on PyPI at ``https://pypi.org/project/<package-name>``

2. Click ``Download files`` under ``Navigation``
#. Click ``Download files`` under ``Navigation``

3. Click ``view hashes`` under ``Source Distribution``
#. Click ``view hashes`` under ``Source Distribution``

4. Copy the ``SHA256`` value
#. Copy the ``SHA256`` value

Create a PR to your conda-forge feedstock:
#. Create a PR to the feedstock repository.

1. Fork the feedstock repository i.g. https://github.com/conda-forge/diffpy.utils-feedstock.
#. If you haven't, fork and clone the forked feedstock repository.

2. Clone the forked repository.
#. Run ``git checkout main && git pull upstream main`` to sync with the main branch.

3. Run ``git checkout main && git pull upstream main`` to sync with the main branch.
#. Run ``git checkout -b <version-number>`` to create a new branch.

4. Run ``git checkout -b <version-number>`` to create a new branch.
#. Open ``recipe/meta.yaml``, modify ``set version`` and ``sha256``.

5. Open ``recipe/meta.yaml``, modify 1) ``set version`` and 2) ``sha256``.
#. Run ``git add recipe/meta.yaml && git commit -m "release: ready for <version-number>"``.

6. Run ``git add recipe/meta.yaml && git commit -m "Release <version-number>"``.
#. Run ``git push --set-upstream origin <version-number>``.

7. Run ``git push --set-upstream origin <version-number>``.
#. Create a PR to ``main``, complete the relevant checklists generated in the PR comment.

8. Create a PR to ``main``, complete the relevant checklists generated in the PR comment, and modify ``meta.yaml`` as needed.
#. Wait for the CI to pass and tag Project Owner for review.

9. Wait for the CI to pass and tag Prof. Billinge for review.
#. Once the PR is merged, in 20 to 30 minutes, verify the latest conda-forge package version from the README badge or by visiting ``https://anaconda.org/conda-forge/<package-name>``. i.e.g, ``https://anaconda.org/conda-forge/diffpy.utils``.

10. Once the PR is merged, verify the latest conda-forge package version from the README badge.

.. _conda-pre-release:
.. _conda-forge-pre-release:

I am familiar with the regular conda release process. How do I do pre-release?
Appendix 1. How do I do pre-release?
------------------------------------------------------------------------------

Generate ``meta.yaml`` by following ``Step 1`` and ``Step 2`` under ``conda-forge: release for the first time`` above. Here are two differences required for pre-release:
Expand All @@ -147,9 +173,15 @@ To install the pre-release build::

For more, read the documentation for pre-release: https://conda-forge.org/docs/maintainer/knowledge_base/#pre-release-builds

Appendix 2. Add a new admin to the conda-forge feedstock
--------------------------------------------------------

Check whether you are an admin listed in the ``meta.yaml`` in the feedstock repository. Create an issue with the title/comment: ``@conda-forge-admin, please add user @username``. Please see an example issue `here <https://github.com/conda-forge/diffpy.pdffit2-feedstock/issues/21>`_.


.. _meta-yaml-info:

Appendix 1. Background info on ``meta.yml``
Appendix 3. Background info on ``meta.yml``
-------------------------------------------

The ``meta.yaml`` file contains information about dependencies, the package version, the license, the documentation link, and the maintainer(s) of the package. In ``meta.yaml``, there are 3 important keywords under the ``requirements`` section: ``build``, ``host``, and ``run`` that are used to specify dependencies.
Expand All @@ -163,3 +195,5 @@ The ``meta.yaml`` file contains information about dependencies, the package vers
To avoid any confusion, there is a separate YAML section called ``build`` above the ``requirements`` section. This section is for setting up the entire operating system.

For more information, please refer to the official documentation: https://conda-forge.org/docs/maintainer/adding_pkgs/#build-host-and-run

.. _conda-forge-add-admin:
Loading

0 comments on commit bd8cbf4

Please sign in to comment.