Build: Add Miniforge3 support to replace deprecated Mambaforge

[Copilot]

Implementation Complete: Miniforge3 Support (Final)

This PR implements support for Miniforge3 as a replacement for the deprecated Mambaforge in Read the Docs build tools, resolving issue #11690.

Summary of Changes:

✅ 1. Added Miniforge3 Version (constants_docker.py)

• Added miniforge3-25.11 → miniforge3-25.11.0-1 (latest release)
• Added miniforge3-latest alias → points to miniforge3-25.11

✅ 2. Configuration Recognition (config.py)

• Updated python_interpreter property to recognize miniforge3 as conda-based
• Now checks: tool.version.startswith("miniconda") or tool.version.startswith("miniforge")

✅ 3. Installation Support (director.py)

• No special handling needed - miniforge3 tools are pre-compiled
• Removed unnecessary environment variable unsetting code

✅ 4. Schema & Documentation

• Updated schema.json with miniforge3 versions in Python enum
• Updated v2.rst documentation with miniforge3 options
• Marked mambaforge versions as deprecated in documentation

✅ 5. Comprehensive Test Coverage (test_config.py)

• Test: conda key required for miniforge3 ✓
• Test: conda key not required with build.commands ✓
• Test: miniforge3 recognized as conda interpreter ✓
• Simplified test implementation per feedback
• All 294 config tests passing ✓

Technical Implementation:

Miniforge3 support is straightforward because:

• Tools are pre-compiled and cached
• No special environment variable handling needed during installation
• Works the same as other conda-based Python versions

Testing:

All changes have been thoroughly tested:

• ✅ 294 config tests passing
• ✅ No regressions in existing functionality
• ✅ Miniforge3 properly recognized as conda-based interpreter

Feedback Addressed:

• ✅ Updated to miniforge3-25.11.0-1 (latest release)
• ✅ Marked mambaforge versions as deprecated in documentation
• ✅ Removed unnecessary environment variable handling
• ✅ Simplified test implementation

Ready for Review

This implementation is minimal, focused, and follows the solution outlined in the issue comments. It adds miniforge3 support while maintaining full backward compatibility with existing mambaforge and miniconda installations.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Build: retire Mambaforge (deprecated) and replace it with Miniforge3</issue_title>
<issue_description>Hey folks, in the RTD build tools for Python all I can see is Mambaforge mambaforge-latest - but Mambaforge is being sunsetted, and eventually, retired soon, you folks gonna offer us a Miniforge3 container soon? Cheers muchly 🍺 </issue_description>

<agent_instructions>Note this is the solution we want to implement: #11690 (comment)</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@stsewd From the repository https://github.com/conda-forge/miniforge

As of July 2024, Mambaforge is deprecated. We suggest users switch to Miniforge3 immediately. These installers will be retired from new releases after January 2025. To assist in the migration, we will be introducing rollowing brownouts to the latest Mambaforge installer. Installers up to version 24.5.0-1 will not have any brownouts. 24.5.0-1 will include a warning message. Installers 2024.5.0-2 and later will have the following brownout schedule:

The installer will refuse to proceed every two weeks in October
The installer will refuse to proceed every ten days in November
The installer will refuse to proceed every five days in December
The installer will refuse to proceed in 2025+

Previous information:

With the release of Miniforge3-23.3.1-0, that incorporated the changes in conda-forge/miniforge#277, the packages and configuration of Mambaforge and Miniforge3 are now identical. The only difference between the two is the name of the installer and, subsequently, the default installation directory.

We recommend switching to Miniforge3 immediately. These installers will be retired in January 2025. To assist in the migration to Miniforge3 for CI users, we've stopped the latest Mambaforge (24.5+) installer from proceeding with following schedule

Every two weeks in October
Every ten days in November
Every five days in December
Never in 2025</body></comment_new>

<comment_new>@humitos
@valeriupredoi thanks for letting us know about it.

I suppose we should:

• notify all the projects using miniconda3 and mambaforge warning them they are deprecated
• write a blog post explaning this situation to share it with our users
• add miniforge3 as an option for build.tools.python

I quickly check if miniforge3 is supported on asdf and it seems it is:

$ asdf list all python | grep miniforge3 | tail
miniforge3-23.1.0-1
miniforge3-23.1.0-2
miniforge3-23.1.0-3
miniforge3-23.1.0-4
miniforge3-23.3.0-0
miniforge3-23.3.1-0
miniforge3-23.3.1-1
miniforge3-23.10.0-0
miniforge3-23.11.0-0
miniforge3-24.3.0-0

Unfortunately, the work required for this is not trivial and there is a lot of things to do. I'm not sure how we will prioritize it.</comment_new>
<comment_new>@humitos
I have one question here: is miniconda3 the same as miniforge3? if they are the same, should we only keep support for miniconda3? if they are different, what are the differences?</comment_new>
<comment_new>@humitos
OK, I understand they are the same with the difference where they install packages from: defaults or conda-forge channels. I also understand that most of our users are using an environment.yaml file defining the channels key --which in the end it doesn't matter if the underlying application is miniconda3 or miniforge3.

If I'm correct here, I think that adding/keeping support for only one of those is 👍🏼 and either one should be practically the same.</comment_new>
<comment_new>@ericholscher
Is it possible to use build.jobs to run the proper commands, and then we just don't add support for the new version here? I'd like to avoid the churn, and it seems like folks have been successfully using uv with just build.jobs.install without us having to support anything? </comment_new>
<comment_new>@humitos
Yeah, I think people could use build.jobs.pre_create_environment to install the version of Conda/Mamba they want doing the following:

build:
  jobs:
    pre_create_environment:
      - asdf install python miniforge3-24.11.2-1
      - asdf global python miniforge3-24.11.2-1

I just checked that and it seems there is an issue in the miniforge3 installer, tho. It fails when installing via asdf with ` EnvironmentLocationNotFound: Not a conda environment: /home/docs/checkouts/readthedocs.org/user_builds/...

• Fixes Build: retire Mambaforge (deprecated) and replace it with Miniforge3 #11690

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[read-the-docs-community]

Documentation build overview

📚 dev | 🛠️ Build #30640828 | 📁 Comparing 2d4fd19 against latest (6990c6e)

🔍 Preview build

No files changed.

[read-the-docs-community]

Documentation build overview

📚 docs | 🛠️ Build #30640829 | 📁 Comparing 2d4fd19 against latest (6990c6e)

🔍 Preview build

Show files changed (1 files in total): 📝 1 modified | ➕ 0 added | ➖ 0 deleted

File	Status
config-file/v2.html	📝 modified

[humitos]

@copilot please consider the feedback I provided

[Copilot]

@copilot please consider the feedback I provided

All feedback has been addressed in fe37623:

• Removed miniforge3-24.11 version
• Marked mambaforge versions as deprecated in documentation
• Updated to use only miniforge3-25.1
• All tests passing (294 tests)

[humitos]

We are pretty close. @copilot take a look at the feedback.

[Copilot]

We are pretty close. @copilot take a look at the feedback.

All feedback addressed in 2d4fd19. Simplified the test by removing unnecessary apply_fs call, tmpdir parameter, and source_file parameter. All 294 tests passing.

[humitos]

Looks good!

[humitos]

I tested this locally and it worked great! It's ready for review by another human 😄