Skip to content

Commit c7363cb

Browse files
scopatzscopatz
authored
Merge pull request #3 from ericdill/cfep02
CFEP-05: conda-forge policy for providing testing/dev/rc builds on anaconda.org/conda-forge
2 parents 5f6fe6f + 25d0215 commit c7363cb

1 file changed

Lines changed: 166 additions & 0 deletions

File tree

‎cfep-05.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
2+
<table>
3+
<tr><td> Title </td><td> Providing pre-release builds on the conda-forge anaconda channel </td>
4+
<tr><td> Status </td><td> Proposed </td></tr>
5+
<tr><td> Author(s) </td><td> Eric Dill &lt;thedizzle@gmail.com&gt;</td></tr>
6+
<tr><td> Created </td><td> Sept 09, 2016</td></tr>
7+
<tr><td> Updated </td><td> Oct 18, 2019</td></tr>
8+
<tr><td> Discussion </td><td> NA </td></tr>
9+
<tr><td> Implementation </td><td> NA </td></tr>
10+
</table>
11+
12+
## Abstract
13+
14+
There are a number of recipe maintainers who have asked for guidance regarding
15+
how to make pre-release builds available with the CI infrastructure on
16+
conda-forge. This document outlines how those builds should be labeled on
17+
anaconda.org so that the more adventurous users can try out these pre-release
18+
packages.
19+
20+
## Motivation
21+
22+
PyPI allows package maintainers to upload "prerelease" builds which users can
23+
then install via
24+
25+
```
26+
pip install PACKAGE_NAME --pre
27+
```
28+
29+
The same semantics are slightly more cumbersome within the Conda ecosystem but
30+
are still manageable. The analogous command with `conda` is (for example):
31+
32+
```
33+
conda install -c conda-forge/label/rc_matplotlib matplotlib
34+
```
35+
36+
We, as the conda-forge community need to arrive at a consensus for what labels
37+
we will affix to packages so that there is a consistent user experience.
38+
39+
## Backwards Compatibility
40+
41+
There are only minimal concerns of backwards compatibility.
42+
The number of feedstocks that issue pre-releases is small, mitigating
43+
backwards compatibility issues.
44+
45+
## Specification
46+
47+
Mark the pre-release package on anaconda.org as "dev" or "rc" by adding them to
48+
the appropriate label.
49+
The semantics of these labels should generally follow the
50+
[guidelines](https://docs.python.org/devguide/devcycle.html#stages) that Python
51+
itself follows.
52+
53+
- "rc": [Beta](https://docs.python.org/devguide/devcycle.html#beta) and [Release
54+
Candidate](https://docs.python.org/devguide/devcycle.html#release-candidate-rc)
55+
(RC). No new features. Bugfix only.
56+
57+
- "dev": [Pre-Alpha](https://docs.python.org/devguide/devcycle.html#pre-alpha)
58+
and [Alpha](https://docs.python.org/devguide/devcycle.html#alpha). These are
59+
still packages that could see substantial changes
60+
between the dev version and the final release.
61+
62+
See the Appendix for dev and rc version order specifics.
63+
64+
To create a `dev` or `rc` package a PR can be issued into the `dev` or `rc` branch of the
65+
feedstock.
66+
This branch must change the `recipe/conda_build_config.yaml` to point to the `dev_<package_name>` or `rc_<package_name>` label.
67+
68+
For example, matplotlib rc releases would include:
69+
```yaml
70+
...
71+
channel_targets:
72+
- conda-forge rc_matplotlib
73+
```
74+
75+
If a pre-release build of B depends on a pre-release build of A, then A should have,
76+
```yaml
77+
...
78+
channel_targets:
79+
- conda-forge rc_A
80+
```
81+
while B should have,
82+
```yaml
83+
...
84+
channel_sources:
85+
- conda-forge/label/rc_A,conda-forge,defaults
86+
channel_targets:
87+
- conda-forge rc_B
88+
```
89+
in `recipe/conda_build_config.yaml` in their respective feedstocks.
90+
91+
NOTE: A rerender needs to happen for these changes to reflect in CI files.
92+
93+
## Alternatives
94+
95+
* Upload pre-release packages to a different anaconda.org user, perhaps
96+
`conda-forge-pre`
97+
* Dump all pre-release packages into one label: "pre"
98+
99+
We understand the proposed approach does not have the same user experience
100+
as `pip --pre`, which seems simpler and easier to use.
101+
Currently this level of functionality is not possible with conda while
102+
maintaining the stability of environment we currently provide.
103+
This CFEP proposes and initial step toward supporting dev/rc releases.
104+
As we explore this functinality more we can re-evaluate the user and maintainer
105+
expreience and how best to provide this functionality.
106+
107+
## FAQ
108+
109+
* What about "alpha" and "beta" labels?
110+
111+
There is not yet heavy use of labels on the conda-forge channel on anaconda.org.
112+
Given the light usage of labels thus far it seems rather unnecessary to
113+
introduce many labels. "dev" and "rc" seem like a nice compromise.
114+
115+
* How do I use labels to install these pre-release packages?
116+
117+
Use the following command, but replace `PACKAGE_NAME` with the package you want
118+
to install and replace `LABEL` with "rc" or "dev":
119+
120+
```
121+
conda install -c conda-forge/label/LABEL_PACKAGE_NAME -c conda-forge PACKAGE_NAME
122+
```
123+
124+
For example, let's install matplotlib from the "rc" label:
125+
126+
```
127+
conda install -c conda-forge/label/rc_matplotlib -c conda-forge matplotlib
128+
```
129+
130+
## Work Items
131+
132+
- Fix intructions to install the package in the README.
133+
134+
Currently, conda-smithy generates incorrect instructions in the README.
135+
This is tracked in https://github.com/conda-forge/conda-smithy/issues/996
136+
137+
- Disable uploading to conda-forge/label/main if sources include other pre-release labels
138+
139+
This is tracked in https://github.com/conda-forge/conda-forge-ci-setup-feedstock/issues/66
140+
141+
## Appendix
142+
143+
If you wish to add numbers to your "dev" or "rc" you should follow the
144+
[guidelines](http://conda.pydata.org/docs/spec.html#build-version-spec) put
145+
forth by Continuum regarding version sorting in `conda`. Also see the [source
146+
code for conda
147+
4.2.13](https://github.com/conda/conda/blob/4.2.13/conda/version.py#L93-L119).
148+
The tl;dr here is that conda sorts as follows:
149+
150+
```
151+
< 1.0
152+
< 1.1dev1 # special case 'dev'
153+
< 1.1.0dev1 # special case 'dev'
154+
== 1.1.dev1 # 0 is inserted before string
155+
< 1.1.0rc1
156+
< 1.1.0
157+
```
158+
159+
So make sure that you ***tag*** your package in such a way that the package name
160+
that conda-build spits out will sort the package uploaded with an "rc" label
161+
higher than the package uploaded with the "dev" label.
162+
163+
164+
## Copyright
165+
166+
This document has been placed in the public domain.

0 commit comments

Comments
 (0)