diff --git a/cfep-05.md b/cfep-05.md new file mode 100644 index 0000000..16c6d95 --- /dev/null +++ b/cfep-05.md @@ -0,0 +1,166 @@ + + + + + + + + + +
Title Providing pre-release builds on the conda-forge anaconda channel
Status Proposed
Author(s) Eric Dill <thedizzle@gmail.com>
Created Sept 09, 2016
Updated Oct 18, 2019
Discussion NA
Implementation NA
+ +## Abstract + +There are a number of recipe maintainers who have asked for guidance regarding +how to make pre-release builds available with the CI infrastructure on +conda-forge. This document outlines how those builds should be labeled on +anaconda.org so that the more adventurous users can try out these pre-release +packages. + +## Motivation + +PyPI allows package maintainers to upload "prerelease" builds which users can +then install via + +``` +pip install PACKAGE_NAME --pre +``` + +The same semantics are slightly more cumbersome within the Conda ecosystem but +are still manageable. The analogous command with `conda` is (for example): + +``` +conda install -c conda-forge/label/rc_matplotlib matplotlib +``` + +We, as the conda-forge community need to arrive at a consensus for what labels +we will affix to packages so that there is a consistent user experience. + +## Backwards Compatibility + +There are only minimal concerns of backwards compatibility. +The number of feedstocks that issue pre-releases is small, mitigating +backwards compatibility issues. + +## Specification + +Mark the pre-release package on anaconda.org as "dev" or "rc" by adding them to +the appropriate label. +The semantics of these labels should generally follow the +[guidelines](https://docs.python.org/devguide/devcycle.html#stages) that Python +itself follows. + +- "rc": [Beta](https://docs.python.org/devguide/devcycle.html#beta) and [Release + Candidate](https://docs.python.org/devguide/devcycle.html#release-candidate-rc) + (RC). No new features. Bugfix only. + +- "dev": [Pre-Alpha](https://docs.python.org/devguide/devcycle.html#pre-alpha) + and [Alpha](https://docs.python.org/devguide/devcycle.html#alpha). These are + still packages that could see substantial changes + between the dev version and the final release. + +See the Appendix for dev and rc version order specifics. + +To create a `dev` or `rc` package a PR can be issued into the `dev` or `rc` branch of the +feedstock. +This branch must change the `recipe/conda_build_config.yaml` to point to the `dev_` or `rc_` label. + +For example, matplotlib rc releases would include: +```yaml +... +channel_targets: + - conda-forge rc_matplotlib +``` + +If a pre-release build of B depends on a pre-release build of A, then A should have, +```yaml +... +channel_targets: + - conda-forge rc_A +``` +while B should have, +```yaml +... +channel_sources: + - conda-forge/label/rc_A,conda-forge,defaults +channel_targets: + - conda-forge rc_B +``` +in `recipe/conda_build_config.yaml` in their respective feedstocks. + +NOTE: A rerender needs to happen for these changes to reflect in CI files. + +## Alternatives + +* Upload pre-release packages to a different anaconda.org user, perhaps + `conda-forge-pre` +* Dump all pre-release packages into one label: "pre" + +We understand the proposed approach does not have the same user experience +as `pip --pre`, which seems simpler and easier to use. +Currently this level of functionality is not possible with conda while +maintaining the stability of environment we currently provide. +This CFEP proposes and initial step toward supporting dev/rc releases. +As we explore this functinality more we can re-evaluate the user and maintainer +expreience and how best to provide this functionality. + +## FAQ + +* What about "alpha" and "beta" labels? + +There is not yet heavy use of labels on the conda-forge channel on anaconda.org. +Given the light usage of labels thus far it seems rather unnecessary to +introduce many labels. "dev" and "rc" seem like a nice compromise. + +* How do I use labels to install these pre-release packages? + +Use the following command, but replace `PACKAGE_NAME` with the package you want +to install and replace `LABEL` with "rc" or "dev": + +``` +conda install -c conda-forge/label/LABEL_PACKAGE_NAME -c conda-forge PACKAGE_NAME +``` + +For example, let's install matplotlib from the "rc" label: + +``` +conda install -c conda-forge/label/rc_matplotlib -c conda-forge matplotlib +``` + +## Work Items + +- Fix intructions to install the package in the README. + + Currently, conda-smithy generates incorrect instructions in the README. + This is tracked in https://github.com/conda-forge/conda-smithy/issues/996 + +- Disable uploading to conda-forge/label/main if sources include other pre-release labels + + This is tracked in https://github.com/conda-forge/conda-forge-ci-setup-feedstock/issues/66 + +## Appendix + +If you wish to add numbers to your "dev" or "rc" you should follow the +[guidelines](http://conda.pydata.org/docs/spec.html#build-version-spec) put +forth by Continuum regarding version sorting in `conda`. Also see the [source +code for conda +4.2.13](https://github.com/conda/conda/blob/4.2.13/conda/version.py#L93-L119). +The tl;dr here is that conda sorts as follows: + +``` +< 1.0 +< 1.1dev1 # special case 'dev' +< 1.1.0dev1 # special case 'dev' +== 1.1.dev1 # 0 is inserted before string +< 1.1.0rc1 +< 1.1.0 +``` + +So make sure that you ***tag*** your package in such a way that the package name +that conda-build spits out will sort the package uploaded with an "rc" label +higher than the package uploaded with the "dev" label. + + +## Copyright + +This document has been placed in the public domain.