Skip to main content

CEP 1 - Purpose and Guidelines

Title CEP Purpose and Guidelines
Status Proposed
Author(s) Jannis Leidel <jleidel@anaconda.com>
Created Jun 29, 2021
Updated Aug 9 2022
Discussion NA
Implementation NA

Abstract

CEPs are the manner in which the conda project community suggests changes to the software project, and outlines how the suggested changes are reviewed. This document provides details on what a CEP is, how to author one, and the workflow used to review these proposals.

What is a CEP

CEP stands for "Conda Enhancement Proposal". A CEP is a document which outlines a suggested change to how the project works. These changes may be technical in manner or may deal with social aspects of the project including governance and conduct. The CEP should provide a concise description of the proposed change as well as the rationale for the change.

CEPs are intended to be the primary mechanism for proposing major changes to how conda works and for documenting both the changes themselves and the decision making process.

CEPs are maintained as text files using Markdown for formatting in the conda/ceps repository. Their revision history is a historical record of the proposed change.

Workflow

The CEP process begins with an idea for a change in how the conda project works. These changes can be technical or address the social aspects of the project. Small changes often do not need a CEP and can be discussed on the conda issue tracker.

More involved or controversial changes should be submitted as CEPs. When it is unclear if a change requires a CEP, ask in a ticket in the conda issue tracker, and the conda core team should be able to provide guidance. The conda core team may solicit CEPs on topics of concern to the community. CEPs should focus on a single issue; broad changes should be split into multiple well-focused CEPs.

Each CEP must have a champion or champions -- someone who will write the CEP in the format described below, submit the CEP as a pull request, follow the discussion on the pull request, and answer questions. Before beginning to write a proposal, it is best to ascertain if the idea is CEP-able. A discussion on the conda-forge mailing list, or as part of a conda community meeting, is the best way to go about this.

Once the champion has asked the conda community whether an idea has any chance of acceptance, a draft CEP should be written following the template in CEP 0 and described below.

While working on the CEP prior to submission, please set its status to draft.

Submission​

Once complete, this draft should be submitted as a pull request to the conda/ceps repository with the status changed to proposed. At this point, members of the conda community will review the submission.

Review​

CEP review will begin once a pull request has been made. All members of the conda community are welcome and encouraged to participate in the review of CEPs in a civil and respectful manner. The CEP champion(s) should be prepared to answer questions on the proposal and make updates to the proposal as recommended by the community.

Resolution​

All CEPs will be resolved as either rejected, accepted or deferred depending on the consensus of the community. Once the community has reached a consensus, a conda maintainer will update the status of the proposal, add a link to the discussion in the table and, regardless of the resolution, merge the pull request with these updates.

CEP Maintenance​

For rejected CEPs, no modifications are made after the pull request is merged. Accepted CEPs should be updated with a link to the pull request(s) of the implementation and the status changed to implemented when the proposed changes have been implemented. Deferred CEPs can be re-submitted in a new pull request if the circumstances that justified deferring instead of accepting or rejecting have changed.

CEP Content

All CEPs should begin with a top level table with the following information:

Title A short title of the proposal
Status Draft | Proposed | Accepted | Rejected | Deferred | Implemented
Author(s) Full Name <full.name@gmail.com>
Created Aug 30, 2016
Updated Aug 30, 2016
Discussion link to the issue where the CEP is being discussed, NA before submission
Implementation link to the PR for the implementation, NA if not available

This table should be followed by an abstract section and then additional sections as needed by the proposal. Some section that may be included if appropriate for the proposal include.

  • Specification -- The technical details of the proposed change.
  • Motivation -- Why the proposed change is needed.
  • Rationale -- Why particular decisions were made in the proposal.
  • Backwards Compatibility -- Will the proposed change break existing packages or workflows.
  • Alternatives -- Any alternatives considered during the design.
  • Sample Implementation -- Links to prototype or a sample implementation of the proposed change.
  • FAQ -- Frequently asked questions (and answers to them).
  • Resolution -- A short summary of the decision made by the community.
  • Reference -- Any references used in the design of the CEP.

A final copyright section is also required.

Pronunciation​

CEP is to be pronounced /sep/.

If you still have doubts about how to actually pronounce it, here is a reference (we accept UK and US pronunciations): https://dictionary.cambridge.org/dictionary/english/cep

Conda capitalization standards​

For the capitalization standards for conda, see the README.

References​

Much of this document was adapted from CFEP 1 - Purpose and Guidelines and PEP 1 -- PEP Purpose and Guidelines, both have been placed in the public domain. The IPEPs: IPython Enhancement Proposals were also referenced for inspiration.

This document is CC0 1.0 Universal.