APEs: Astropy Proposals for Enhancement
APEs are documents to address non-trivial enhancements that require discussion and thought beyond a single Pull Request. This is intended to mirror the long-standing Python Enhancement Proposal process, but generally not quite as formally. Normally a proposal goes through various phases of consideration. Discussion is expected to take place using existing mechanisms (astropy-dev, github, hangouts, etc), and eventually a decision is made regarding whether the proposal should be accepted, rejected, or modified.
|1||APE Purpose and Process||2013-Nov-08|
|2||Astropy Release Cycle and Version Numbering||2013-Dec-11|
|4||Astropy Setup Helpers||2014-Jun-28|
|5||Coordinates Subpackage Plan||2014-Jan-22|
|6||Enhanced Character Separated Values table format||2015-Jan-26|
|8||Astropy Community Code of Conduct||2015-May-04|
|10||Roadmap for Python 3-only support||2016-Aug-22|
|12||Using Cookiecutter for the package-template||2017-Mar-28|
|13||Vision for Astropy Spectroscopic Tools||2017-Dec-12|
|14||A shared Python interface for World Coordinate Systems||2018-Feb-28|
|15||An Updated Model for the Affiliated Package Ecosystem||2018-May-14|
Proposing a new APE
New APEs should be created using the
APEtemplate.rst file in this repository.
Fork the repository, copy
APE_<some_working_name>.rst and issue a Pull Request with that file once
you've written it up (little explanation is required in the PR itself given that
the document has all the content - usually it's easiest to just paste in the
abstract). The APE number will be assigned once the PR is merged.
Note that there is not much point to making proposals unless someone or some group has signed up to implement it if the APE is accepted (typically this would involve the author or authors of the APE). Just issuing an APE in order to spur others to do work is not generally going to be received well. Generally, an implementation is expected before an APE can be considered fully accepted. For proposals that require extensive work that few are willing to perform without some assurance it will be accepted, provisional acceptance is an option. For serious consideration it is usually good to show that detailed technical aspects have been played with in real code rather (even if it isn't a complete implementation).
The final decision on accepting or rejecting APEs lies with the Astropy Coordination Committee. Once the community discussion on the APE has wound down, the committee discusses the APE and makes a final decision on acceptance or rejection. One of the committee members should then:
- Fill in the "Decision rationale" section of the APE with a description of why the APE was accepted or rejected, including a summary of the community's discussion as relevant.
- Update the "date-last-revised" to the day of merging and "status" to "Accepted" or "Rejected".
- If necessary, rename the APE file to be
APE##.rst, where ## is the next free number on the list of APEs.
- If the APE is accepted, add a commit to the APE which puts the APE into the "Accepted APEs" table of the repository's README.
- Leave a brief comment in the PR indicating the result, and merge the PR with the above changes.
- Upload the APE to Zenodo to give it a DOI (see next section).
- Send an email to astropy-dev announcing the acceptance (In general this should just point to the accepted APE rather than providing additional decision rationale).
Uploading an APE to Zenodo
Go to https://zenodo.org/deposit/new, upload the .rst file, and set the fields to the following:
|Zenodo field||Set to|
|Communities||The Astropy Project|
|Publication type||Technical note|
|Publication Date||The date-last-revised of the APE (which should be the same as the accepted date for new APEs)|
|Title||Astropy Proposal for Enhancement <number>: <title> (APE <number>)|
|Authors||The APE authors (directly from the APE text, but with ORCIDs if possible)|
|Description||The APE abstract|
|Related/alternate identifiers||Github link to the APE file at the specific merge commit (e.g. https://github.com/astropy/astropy-APEs/blob/42951733ac42c0ea178d8df30705274a43c93091/APE1.rst) as "is supplemented by this upload". If this is a revised version, this should be the URL of the commit where the APE was revised.|
In the cases where an updated APE requires updating (e.g. references to a new APE that supercedes it, clarifying information that emerges after the APE is accepted, etc.), changes can be made directly via PR, but the "date-last-revised" should be updated in the APE. Additionally, the Zenodo entry will need to be updated with a new version of the APE (not a completely new Zenodo entry), by using the "New version" button and then filling out the forms as described above.