From 188f2103f65837a1fbe0934dd66b7a1c9931e668 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Wed, 27 Jan 2021 14:07:36 -0700 Subject: [PATCH 01/16] Add first draft SymPEP-template.md This is based in large part on the NEP template https://numpy.org/neps/nep-template.html, with some additions. --- SymPEP-template.md | 131 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 SymPEP-template.md diff --git a/SymPEP-template.md b/SymPEP-template.md new file mode 100644 index 0000000..080ddc2 --- /dev/null +++ b/SymPEP-template.md @@ -0,0 +1,131 @@ +SymPEP X — Template and Instructions +==================================== + +**Author** list of authors' real names and optionally, email addresses +**Status** Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded +**Type** Standards Track | Informational| Process +**Created** date created on, in yyyy-mm-dd format +**Resolution** url to discussion (required for Accepted | Rejected | Withdrawn) + +## Abstract + +The abstract should be a short description of what the SymPEP will achieve. + +Note that the — in the title is an em dash, not -. + +## Motivation and Scope + +This section describes the need for the proposed change. It should describe +the existing problem, who it affects, what it is trying to solve, and why. +This section should explicitly address the scope of and key requirements for +the proposed change. + +## Usage and Impact + +This section describes how users of SymPy will use features described in this +SymPEP. It should be comprised mainly of code examples that wouldn't be possible +without acceptance and implementation of this SymPEP, as well as the impact the +proposed changes would have on the ecosystem. This section should be written +from the perspective of the users of SymPy, and the benefits it will provide +them; and as such, it should include implementation details only if +necessary to explain the functionality. + +Note that this section should *not* be treated as documentation of the +proposed functionality. Documentation should be included in the implementation +itself. The purpose of this section is to motivate why the change should be +made in the first place. See [SymPEP 1](SymPEP-0001) for more information. + +## Backwards compatibility + +This section describes the ways in which the SymPEP breaks backward compatibility. + +The mailing list post will contain the SymPEP up to and including this section. +Its purpose is to provide a high-level summary to users who are not interested +in detailed technical discussion, but may have opinions around, e.g., usage and +impact. + +## Detailed description + +This section should provide a detailed description of the proposed change. +It should include examples of how the new functionality would be used, +intended use-cases and pseudocode illustrating its use. + +## Related Work + +This section should list relevant and/or similar technologies, possibly in other +libraries. It does not need to be comprehensive, just list the major examples of +prior and relevant art. + +## Implementation + +This section lists the major steps required to implement the SymPEP. Where +possible, it should be noted where one step is dependent on another, and which +steps may be optionally omitted. Where it makes sense, each step should +include a link to related pull requests as the implementation progresses. + +Any pull requests or development branches containing work on this SymPEP should +be linked to from here. (A SymPEP does not need to be implemented in a single +pull request if it makes sense to implement it in discrete phases). + +## Alternatives + +If there were any alternative solutions to solving the same problem, they should +be discussed here, along with a justification for the chosen approach. + +## Discussion + +This section may just be a bullet list including links to any discussions +regarding the SymPEP: + +- This includes links to mailing list threads or relevant GitHub issues. + +## References + +Any references should be listed here. Note this does not include links to +discussions about the SymPEP, which are listed in the previous section. For +online resources, freely accessible and stable online resources such as +Wikipedia, Wolfram MathWorld, and the NIST Digital Library of Mathematical +Functions (DLMF), which are unlikely to suffer from hyperlink rot, should be +preferred. Non-online references such as textbook or literature references may +also be used here. + +## Copyright + +Each SymPEP must either be explicitly labeled as placed in the public domain +(see this SymPEP as an example) or licensed under the [Open Publication +License](https://www.opencontent.org/openpub/) + +This document has been placed in the public domain. [1]_ + +## Extra Notes About SymPEPs + +NOTE: This section is not part of the template. It should not be included in +any SymPEPs. It is a list of notes of things that apply to all parts of the +above template. + +Some extra notes about writing a SymPEP: + +- All SymPEPs live in the [SymPEPs + repository](https://github.com/sympy/SymPEPs/) on GitHub. All proposed + SymPEPs should be made as pull requests to that repo (see [SymPEP + 1](SymPEP-0001)). +- All SymPEP documents should be written in Markdown, following this template. + The Markdown should be compatible with GitHub Flavored Markdown, so that the + SymPEPs are viewable on GitHub. This means that Markdown features + not supported by GitHub, such as footnotes, should be avoided. + +- Any references to other SymPEPs should be written as internal links, e.g., + [SymPEP 1](SymPEP-0001). +- Images or diagrams may be included in the SymPEP if they improve the + understanding of the discussion. Code examples should always be included as + plain text. Any image or diagram should be accompanied by corresponding text + describing what is in it. Images should be stored in an `images` directory + at the root of the SymPEPs repository. Images should be titled like + `XXXX-image-name.svg` where `XXXX` is the four digit number of the SymPEP + and `image-name` is the name of the image. For example, + `images/0001-process-diagram.svg`. Vector images are preferred when + possible. Note that images should only be included when they significantly + improve the discussion in the SymPEP. The vast majority of SymPEPs should + not include images. From 105495c7736fa654d8c09f9ed1201b63ea494e00 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Wed, 27 Jan 2021 16:06:24 -0700 Subject: [PATCH 02/16] Update some stuff in the template --- SymPEP-template.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/SymPEP-template.md b/SymPEP-template.md index 080ddc2..568a384 100644 --- a/SymPEP-template.md +++ b/SymPEP-template.md @@ -3,7 +3,7 @@ SymPEP X — Template and Instructions **Author** list of authors' real names and optionally, email addresses **Status** Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded -**Type** Standards Track | Informational| Process +**Type** Standards Track | Informational | Process **Created** date created on, in yyyy-mm-dd format **Resolution** url to discussion (required for Accepted | Rejected | Withdrawn) @@ -91,11 +91,10 @@ also be used here. ## Copyright -Each SymPEP must either be explicitly labeled as placed in the public domain -(see this SymPEP as an example) or licensed under the [Open Publication -License](https://www.opencontent.org/openpub/) +Each SymPEP must be explicitly labeled as placed in the public domain, using +the below sentence (the below sentence also applies to this template). -This document has been placed in the public domain. [1]_ +This document has been placed in the public domain. ## Extra Notes About SymPEPs @@ -109,6 +108,12 @@ Some extra notes about writing a SymPEP: repository](https://github.com/sympy/SymPEPs/) on GitHub. All proposed SymPEPs should be made as pull requests to that repo (see [SymPEP 1](SymPEP-0001)). +- The number corresponding to a SymPEP will be assigned when it is first + proposed to the community. You may use `XXXX` as a placeholder number until + this is done. +- The file for a SymPEPs should be named `SymPEP-XXXX.md` where `XXXX` is a + four digit number, preceded with leading 0s. It should be placed at the root + of the [SymPEPs repository](https://github.com/sympy/SymPEPs/). - All SymPEP documents should be written in Markdown, following this template. The Markdown should be compatible with GitHub Flavored Markdown, so that the SymPEPs are viewable on GitHub. This means that Markdown features From 7947a67a676d1c54c40c3c4c434b16aed03a1704 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Wed, 27 Jan 2021 16:21:37 -0700 Subject: [PATCH 03/16] Add SymPEP 1 This is based in large part on NEP 0, which is itself based on PEP 1. However, there are significant deviations from both. --- SymPEP-0001.md | 218 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 SymPEP-0001.md diff --git a/SymPEP-0001.md b/SymPEP-0001.md new file mode 100644 index 0000000..b4e55f0 --- /dev/null +++ b/SymPEP-0001.md @@ -0,0 +1,218 @@ +# SymPEP 1 --- SymPEP Purpose and Process + +**Author** Aaron Meurer +**Status** Draft +**Type** Process +**Created** 2021-01-27 +**Resolution** + +## Abstract + +SymPEPs are a formal process whereby important changes are proposed and +discussed. Corresponding to each SymPEP is a document that outlines the +proposed change(s), the discussion around those changes, and motivation for +that change. This document outlines the details of the SymPEP process and +corresponding documents. + +## What is a SymPEP? + +SymPEP stands for "SymPy Enhancement Proposal". SymPEPs represent a formal +process whereby important changes are proposed and discussed in the SymPy +community. Corresponding to each SymPEP is a SymPEP document which outlines +the proposal and corresponding discussion. SymPEPs are based on +[PEP](https://www.python.org/dev/peps/) process used by the Python language +community to propose changes to the Python language. It also takes motivations +from other similar processes in communities adjacent to SymPy, such as the +[NEP](https://numpy.org/neps/nep-0000.html) process for NumPy and the +[MEP](https://matplotlib.org/devel/MEP/index.html) process for Matplotlib. +However, the SymPEP process differs from these processes in many ways, so +those who may already be familiar with similar processes from other +communities should read this document to understand how it works for SymPEPs. + +In particular, SymPEPs are significantly less formal than Python PEPs. + +## Types + +There are three kinds of SymPEPs: + +A **Standards Track** SymPEP describes a new feature or important change for +SymPy. + +An **Informational** SymPEP describes a SymPy design issue, or provides general +guidelines or information to the Python community, but does not propose a new +feature. Informational SymPEPs do not necessarily represent a SymPy community +consensus or recommendation, so users and implementers are free to ignore +Informational SymPEPs or follow their advice. + +A **Process** SymPEP describes a process surrounding SymPy, or proposes a +change to (or an event in) a process. Process SymPEPs are like Standards Track +SymPEPs but apply to areas other than the SymPy library itself. They may +propose an implementation, but not to SymPy’s codebase; they require community +consensus. Examples include procedures, guidelines, changes to the +decision-making process, and changes to the tools or environment used in SymPy +development. Any meta-SymPEP is also considered a Process SymPEP. + +## Purpose + +The SymPEP process and corresponding documents serve several purposes: + +- To decide, as a community, whether a proposed change should be made. +- To decide on the process by which a change will be implemented, for example, + whether the change should be implemented in several stages, whether + intermediate releases are required for things like deprecations, and so on. +- To document the above discussions and decisions for future reference. +- To document the motivations for a change from the perspective of end users + who may be affected by it. Here "end users" means both users of the SymPy + library, as well as developers working on parts of SymPy itself which may be + affected by the change. + +Importantly, **a SymPEP is not documentation** for the proposed change. End +user documentation should be included with the implementation of the feature +in the corresponding SymPy documentation. This also means that other +documentation should not cross-reference a SymPEP as if it were documentation +for a feature. Even technical discussion of a feature should be documented +separately from a SymPEP. The reason is that SymPEPs will necessarily include +details that are irrelevant to the final implementation, such as discussions +of alternate implementations which were rejected and discussions of +implementation of the change. + +## SymPEP Workflow + +Discussions around a proposed change may begin informally on the mailing list +or SymPy issue tracker. However, once it is decided that the formal SymPEP +process is desired for a change, the discussion should move to the +[SymPEP repository](https://github.com/sympy/SymPEPs) on GitHub. + +Every SymPEP must have a champion. This is a person who is responsible for +writing the SymPEP, leads the discussion around it, and tries to create +consensus around it. + +The author of a SymPEP should fork the repository and create a pull request +with a new SymPEP document based on the [SymPEP template](SymPEP-template). +The SymPEP document may be named `SymPEP-XXXX.md` until a number is assigned. +One of the core SymPy developers will then assign a number to the SymPEP, in +which case `XXXX` should be replaced with the number with leading 0s. The +person who assigns the number should also update the +[README](https://github.com/sympy/SymPEPs/blob/main/README.md) of the main +[SymPEP repository](https://github.com/sympy/SymPEPs) to list that number. +Numbers should be assigned to SymPEPs as soon as it is determined that they +are a legitimate proposal. If a SymPEP ends up being rejected or postponed, it +keeps its number, as rejection or postponement status is still a discussion +that should be documented in the SymPEP. SymPEP numbers should generally be +assigned in increasing numeric order. + +Discussion on the SymPEP should then continue on the SymPEP pull request. +Discussions may also take place in other places, such as [GitHub +discussions](https://github.com/sympy/SymPEPs/discussions) or the [mailing +list](http://groups.google.com/group/sympy). All discussions should be +cross-referenced in the "Discussions" section of the SymPEP document. + +For each SymPEP, the community should decide whether a draft implementation is +needed before acceptance or not. For instance, if a SymPEP concerns the +details of how a feature is implemented, it should be accepted before that +happens. On the other hand, the community may decide that it cannot come to a +consensus about a SymPEP until a draft implementation is proposed. + +Once the community reaches a consensus about a SymPEP, the status of a SymPEP +should be updated (see below). This consensus may be to accept or to reject +the SymPEP, or to defer it. Here the "community" refers to the broader +community that has a stake in the SymPEP, not just the core SymPy developers. +The purpose of the SymPEP process is not to create a cabal of decision makers, +but rather to enhance the involvement of the broader SymPy community in the +decision making process. + +### Status + +The **status** section at the top of the SymPEP document (see the +[template](SymPEP-template)) should be updated according to the current status +of the SymPEP. + +All SymPEPs should be created with the **Draft** status. **Draft** status +SymPEPs generally live in a pull request. + +Eventually, after discussion, there may be a consensus that the SymPEP should +be accepted–see the next section for details. At this point the status +becomes **Accepted**. + +Once a SymPEP has been **Accepted**, the reference implementation must be +completed. When the reference implementation is complete and incorporated into +the main source code repository, the status will be changed to **Final**. + +A SymPEP can also be assigned status **Deferred**. The SymPEP author or a core +developer can assign the SymPEP this status when no progress is being made on +the SymPEP. + +A SymPEP can also be **Rejected**. Perhaps after all is said and done it was +not a good idea. It is still important to have a record of this fact. The +**Withdrawn** status is similar—it means that the SymPEP author themselves has +decided that the SymPEP is actually a bad idea, or has accepted that a +competing proposal is a better alternative. + +SymPEPs can also be **Superseded** by a different SymPEP, rendering the +original obsolete. + +Process SymPEPs may also have a status of **Active** if they are never meant +to be completed, e.g. SymPEP 1 (this SymPEP). + +### Merging the SymPEP Document Pull Request + +Whenever a SymPEP moves from the **Draft** status to one of the other above +statuses, the header should be updated, and the corresponding pull request +should be merged. This way the document lives inside of the SymPEP repository +proper. SymPEPs that are merged are not set in stone, and may be updated by +future pull requests (although SymPEPs that are **Accepted** should generally +not be significantly modified once they have reached that status). The purpose +of merging is simply to make the SymPEP visible in the repository, even if it +isn't yet accepted or rejected. SymPEP discussions that have stalled should +also be merged, so that the SymPEP becomes visible in the SymPEP repository +proper—again, discussion may be picked up again with a new pull request. + +## Accepting a SymPEP + +Once a SymPEP is Accepted by consensus of all interested contributors, an +email should be sent to the [SymPy mailing +list](http://groups.google.com/group/sympy) with a subject like: + + Proposal to accept SymPEP #: + +In the body of your email, you should: + +- link to the latest version of the SymPEP, + +- briefly describe any major points of contention and how they were resolved, + +- include a sentence like: “If there are no substantive objections within 7 + days from this email, then the SymPEP will be accepted; see SymPEP 1 for + more details.” + +After you send the email, add the the email thread to the Discussion section +of the SymPEP, so that people can find it later. + +Generally the SymPEP author will be the one to send this email, but anyone can +do it – the important thing is to make sure that everyone knows when a SymPEP +is on the verge of acceptance, and give them a final chance to respond. If +there’s some special reason to extend this final comment period beyond 7 days, +then that’s fine, just say so in the email. It shouldn’t be less than 7 days, +because sometimes people are traveling or similar and need some time to +respond. + +In general, the goal is to make sure that the community has consensus, not +provide a rigid policy for people to try to game. When in doubt, err on the +side of asking for more feedback and looking for opportunities to compromise. + +If the final comment period passes without any substantive objections, then +the SymPEP can officially be marked **Accepted**. A followup email should then +be sent notifying the list. Update the SymPEP by setting its **Status** to +**Accepted**, and its **Resolution** header to a link to your followup email. +The SymPEP pull request should be merged at this time, if it hasn't been +already, so that it is visible in the SymPEP repository proper. + +If there are substantive objections, then the SymPEP remains in Draft state, +discussion continues as normal, and it can be proposed for acceptance again +later once the objections are resolved. + +## Discussion + +## Copyright + +This document has been placed in the public domain. From 68f05463c1f71c06b3c210b4cab552ba4bcda836 Mon Sep 17 00:00:00 2001 From: Aaron Meurer <asmeurer@gmail.com> Date: Wed, 27 Jan 2021 16:27:21 -0700 Subject: [PATCH 04/16] Add links to discussions to SymPEP 1 --- SymPEP-0001.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index b4e55f0..bfb1a58 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -213,6 +213,10 @@ later once the objections are resolved. ## Discussion +- [Initial mailing list post proposing + SymPEPs](https://groups.google.com/forum/#!msg/sympy/5RVMiWuCjoA/lr64dS1BBAAJ) +- [sympy/SymPEPs#2](https://github.com/sympy/SymPEPs/pull/2) + ## Copyright This document has been placed in the public domain. From e7787610575c99d31a16359681bde8edce951df6 Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Thu, 31 Aug 2023 09:49:21 +0200 Subject: [PATCH 05/16] Address concerns since Aaron's last work on the document. --- SymPEP-0001.md | 153 +++++++++++++++++++++++++++---------------------- 1 file changed, 86 insertions(+), 67 deletions(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index bfb1a58..ef35da3 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -1,10 +1,10 @@ # SymPEP 1 --- SymPEP Purpose and Process -**Author** Aaron Meurer -**Status** Draft -**Type** Process -**Created** 2021-01-27 -**Resolution** +**Author** Aaron Meurer, Jason K. Moore +**Status** Draft +**Type** Process +**Created** 2021-01-27 +**Resolution** ## Abstract @@ -18,34 +18,26 @@ corresponding documents. SymPEP stands for "SymPy Enhancement Proposal". SymPEPs represent a formal process whereby important changes are proposed and discussed in the SymPy -community. Corresponding to each SymPEP is a SymPEP document which outlines -the proposal and corresponding discussion. SymPEPs are based on +community. Corresponding to each SymPEP is a SymPEP document which outlines the +proposal and corresponding discussion. SymPEPs are based on the [PEP](https://www.python.org/dev/peps/) process used by the Python language community to propose changes to the Python language. It also takes motivations from other similar processes in communities adjacent to SymPy, such as the [NEP](https://numpy.org/neps/nep-0000.html) process for NumPy and the [MEP](https://matplotlib.org/devel/MEP/index.html) process for Matplotlib. -However, the SymPEP process differs from these processes in many ways, so -those who may already be familiar with similar processes from other -communities should read this document to understand how it works for SymPEPs. - -In particular, SymPEPs are significantly less formal than Python PEPs. +However, the SymPEP process differs from these processes in some ways, so those +who may already be familiar with similar processes from other communities +should read this document to understand how it works for SymPEPs. ## Types There are three kinds of SymPEPs: -A **Standards Track** SymPEP describes a new feature or important change for -SymPy. - -An **Informational** SymPEP describes a SymPy design issue, or provides general -guidelines or information to the Python community, but does not propose a new -feature. Informational SymPEPs do not necessarily represent a SymPy community -consensus or recommendation, so users and implementers are free to ignore -Informational SymPEPs or follow their advice. +A **Software Track** SymPEP describes a new feature or important change for the +code in SymPy. -A **Process** SymPEP describes a process surrounding SymPy, or proposes a -change to (or an event in) a process. Process SymPEPs are like Standards Track +A **Process** SymPEP describes a process related to SymPy, or proposes a +change to (or an event in) a process. Process SymPEPs are like Software Track SymPEPs but apply to areas other than the SymPy library itself. They may propose an implementation, but not to SymPy’s codebase; they require community consensus. Examples include procedures, guidelines, changes to the @@ -78,40 +70,60 @@ implementation of the change. ## SymPEP Workflow -Discussions around a proposed change may begin informally on the mailing list -or SymPy issue tracker. However, once it is decided that the formal SymPEP -process is desired for a change, the discussion should move to the -[SymPEP repository](https://github.com/sympy/SymPEPs) on GitHub. - -Every SymPEP must have a champion. This is a person who is responsible for -writing the SymPEP, leads the discussion around it, and tries to create -consensus around it. - -The author of a SymPEP should fork the repository and create a pull request -with a new SymPEP document based on the [SymPEP template](SymPEP-template). -The SymPEP document may be named `SymPEP-XXXX.md` until a number is assigned. -One of the core SymPy developers will then assign a number to the SymPEP, in -which case `XXXX` should be replaced with the number with leading 0s. The -person who assigns the number should also update the +Discussions around a proposed change typically begin informally on the mailing +list or SymPy issue/pull-request tracker. However, once it is decided that the +formal SymPEP process is desired for a change, the discussion should move to +the [SymPEP repository](https://github.com/sympy/SymPEPs) on GitHub. + +Not all significant changes or additions to SymPy require a SymPEP. If the +change would benefit from extended discussion or needs a roadmap for +implementation, a SymPEP should be considered. If unsure, consult with the +community on the currently active discussion forum. Most all changes to and +decisions regarding SymPy can be made through issues and pull requests, so it +is best to start with one or the other. Examples of things that likely need a +SymPEP are: major version changes (1.X.X -> 2.0), large breaks in backwards +compatibility, adding new primary packages within SymPy, adding hard +dependencies, introduction of development practices or tools all developers +need to adopt, etc. Long term SymPy policies and goals should also be discussed +and developed as SymPEPs. Statements of these policies and goals should be +incorporated into the SymPy documentation, as determined in the associated +SymPEP. + +Every SymPEP must have at least one champion. The champion(s) are persons who +are responsible for writing the SymPEP, leading the discussions around it, and +developing consensus around it. + +The author of a SymPEP should fork the repository and create a draft pull +request with a new SymPEP document based on the [SymPEP +template](SymPEP-template). The SymPEP document may be named `SymPEP-XXXX.md` +until a number is assigned. Once the author completes all information in the +template and would like it to be reviewed, one of the core SymPy developers should +decide if the proposal is a legtimate proposal and then assign a number to the +SymPEP, in which case `XXXX` should be replaced with the number with leading +0s. The pull request can then be moved to an open pull request and is ready for +community feedback and discussion but remains in draft state. The person who +assigns the number should also update the [README](https://github.com/sympy/SymPEPs/blob/main/README.md) of the main [SymPEP repository](https://github.com/sympy/SymPEPs) to list that number. -Numbers should be assigned to SymPEPs as soon as it is determined that they -are a legitimate proposal. If a SymPEP ends up being rejected or postponed, it -keeps its number, as rejection or postponement status is still a discussion -that should be documented in the SymPEP. SymPEP numbers should generally be -assigned in increasing numeric order. - -Discussion on the SymPEP should then continue on the SymPEP pull request. +Numbers should be assigned to SymPEPs as soon as it is determined that they are +a legitimate proposal. If a SymPEP is not deemed necessary, the author should +rework the SymPEP or move it to a normal pull request or issue on the main +SymPy repository. If a SymPEP ends up being rejected or postponed, it keeps its +number, as rejection or postponement status is still a discussion that should +be documented in the SymPEP. SymPEP numbers should generally be assigned in +increasing numeric order. + +Discussion on the SymPEP should then continue on the open pull request. Discussions may also take place in other places, such as [GitHub discussions](https://github.com/sympy/SymPEPs/discussions) or the [mailing list](http://groups.google.com/group/sympy). All discussions should be cross-referenced in the "Discussions" section of the SymPEP document. -For each SymPEP, the community should decide whether a draft implementation is -needed before acceptance or not. For instance, if a SymPEP concerns the -details of how a feature is implemented, it should be accepted before that -happens. On the other hand, the community may decide that it cannot come to a -consensus about a SymPEP until a draft implementation is proposed. +For each SymPEP, the community should decide whether a draft implementation of +the change is needed before acceptance or not. For instance, if a SymPEP +concerns the details of how a feature is implemented, it should be accepted +before that happens. On the other hand, the community may decide that it cannot +come to a consensus about a SymPEP until a draft implementation is proposed. Once the community reaches a consensus about a SymPEP, the status of a SymPEP should be updated (see below). This consensus may be to accept or to reject @@ -125,14 +137,15 @@ decision making process. The **status** section at the top of the SymPEP document (see the [template](SymPEP-template)) should be updated according to the current status -of the SymPEP. +of the SymPEP. Do not confuse this with the "draft/open pull request state on +Github". All SymPEPs should be created with the **Draft** status. **Draft** status SymPEPs generally live in a pull request. Eventually, after discussion, there may be a consensus that the SymPEP should -be accepted–see the next section for details. At this point the status -becomes **Accepted**. +be accepted–see the next section for details. At this point the status becomes +**Accepted**. Once a SymPEP has been **Accepted**, the reference implementation must be completed. When the reference implementation is complete and incorporated into @@ -144,15 +157,15 @@ the SymPEP. A SymPEP can also be **Rejected**. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. The -**Withdrawn** status is similar—it means that the SymPEP author themselves has -decided that the SymPEP is actually a bad idea, or has accepted that a -competing proposal is a better alternative. +**Withdrawn** status is similar, it means that the SymPEP author themselves has +decided that the SymPEP is actually a bad idea or has accepted that a competing +proposal is a better alternative. SymPEPs can also be **Superseded** by a different SymPEP, rendering the original obsolete. -Process SymPEPs may also have a status of **Active** if they are never meant -to be completed, e.g. SymPEP 1 (this SymPEP). +Process SymPEPs may also have a status of **Active** if they are never meant to +be completed, e.g. SymPEP 1 (this SymPEP). ### Merging the SymPEP Document Pull Request @@ -169,8 +182,8 @@ proper—again, discussion may be picked up again with a new pull request. ## Accepting a SymPEP -Once a SymPEP is Accepted by consensus of all interested contributors, an -email should be sent to the [SymPy mailing +Once a SymPEP is Accepted by consensus of all interested contributors, an email +should be sent to the [SymPy mailing list](http://groups.google.com/group/sympy) with a subject like: Proposal to accept SymPEP #<number>: <title> @@ -182,17 +195,17 @@ In the body of your email, you should: - briefly describe any major points of contention and how they were resolved, - include a sentence like: “If there are no substantive objections within 7 - days from this email, then the SymPEP will be accepted; see SymPEP 1 for - more details.” + days from this email, then the SymPEP will be accepted; see SymPEP 1 for more + details.” -After you send the email, add the the email thread to the Discussion section -of the SymPEP, so that people can find it later. +After you send the email, add the the email thread to the Discussion section of +the SymPEP, so that people can find it later. Generally the SymPEP author will be the one to send this email, but anyone can -do it – the important thing is to make sure that everyone knows when a SymPEP -is on the verge of acceptance, and give them a final chance to respond. If -there’s some special reason to extend this final comment period beyond 7 days, -then that’s fine, just say so in the email. It shouldn’t be less than 7 days, +do it. The important thing is to make sure that everyone knows when a SymPEP is +on the verge of acceptance, and give them a final chance to respond. If there's +some special reason to extend this final comment period beyond 7 days, then +that's fine, just say so in the email. It shouldn't be less than 7 days, because sometimes people are traveling or similar and need some time to respond. @@ -200,6 +213,12 @@ In general, the goal is to make sure that the community has consensus, not provide a rigid policy for people to try to game. When in doubt, err on the side of asking for more feedback and looking for opportunities to compromise. +It is also important that SymPEPs are a mechanism to enable change as opposed +to hindering and slowing change. The general approach of reviewers should be to +help the author get it to a state that can be accepted or by offering +alternative proposals. SymPEPs shouldn't be the place where energy and ideas +die. + If the final comment period passes without any substantive objections, then the SymPEP can officially be marked **Accepted**. A followup email should then be sent notifying the list. Update the SymPEP by setting its **Status** to From 99eebeb103cdb915a48e34bcc5c077feae1313d0 Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Thu, 31 Aug 2023 09:58:59 +0200 Subject: [PATCH 06/16] Fixed linebreaks in the template. --- SymPEP-template.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/SymPEP-template.md b/SymPEP-template.md index 568a384..e9fb106 100644 --- a/SymPEP-template.md +++ b/SymPEP-template.md @@ -1,11 +1,11 @@ SymPEP X — Template and Instructions ==================================== -**Author** list of authors' real names and optionally, email addresses -**Status** Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded -**Type** Standards Track | Informational | Process -**Created** date created on, in yyyy-mm-dd format -**Resolution** url to discussion (required for Accepted | Rejected | Withdrawn) +**Author** list of authors' real names and optionally, email addresses +**Status** Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded +**Type** Standards Track | Informational | Process +**Created** date created on, in yyyy-mm-dd format +**Resolution** url to discussion (required for Accepted | Rejected | Withdrawn) ## Abstract From b368841f724ec73b14b1fd3f25776c7d8f3ff428 Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Thu, 31 Aug 2023 13:04:34 +0200 Subject: [PATCH 07/16] Addressed Oscar's comments. --- SymPEP-0001.md | 85 +++++++++++++++++++++++++++++++--------------- SymPEP-template.md | 5 ++- 2 files changed, 59 insertions(+), 31 deletions(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index ef35da3..17ccd6d 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -31,7 +31,7 @@ should read this document to understand how it works for SymPEPs. ## Types -There are three kinds of SymPEPs: +There are two kinds of SymPEPs: A **Software Track** SymPEP describes a new feature or important change for the code in SymPy. @@ -55,18 +55,18 @@ The SymPEP process and corresponding documents serve several purposes: - To document the above discussions and decisions for future reference. - To document the motivations for a change from the perspective of end users who may be affected by it. Here "end users" means both users of the SymPy - library, as well as developers working on parts of SymPy itself which may be - affected by the change. + library, developers working on parts of SymPy itself which may be affected by + the change, and developers of downstream libraries that depend on SymPy. Importantly, **a SymPEP is not documentation** for the proposed change. End -user documentation should be included with the implementation of the feature -in the corresponding SymPy documentation. This also means that other -documentation should not cross-reference a SymPEP as if it were documentation -for a feature. Even technical discussion of a feature should be documented -separately from a SymPEP. The reason is that SymPEPs will necessarily include -details that are irrelevant to the final implementation, such as discussions -of alternate implementations which were rejected and discussions of -implementation of the change. +user documentation should be included with the implementation of the feature in +the corresponding SymPy documentation. This also means that other documentation +should not rely on cross-referencing a SymPEP as if it were documentation for a +feature. Even technical discussion of a feature should be documented separately +from a SymPEP. The reason is that SymPEPs will necessarily include details that +are irrelevant to the final implementation, such as discussions of alternate +implementations which were rejected and discussions of implementation of the +change. ## SymPEP Workflow @@ -78,7 +78,7 @@ the [SymPEP repository](https://github.com/sympy/SymPEPs) on GitHub. Not all significant changes or additions to SymPy require a SymPEP. If the change would benefit from extended discussion or needs a roadmap for implementation, a SymPEP should be considered. If unsure, consult with the -community on the currently active discussion forum. Most all changes to and +community on the currently active discussion forum. Most changes to and decisions regarding SymPy can be made through issues and pull requests, so it is best to start with one or the other. Examples of things that likely need a SymPEP are: major version changes (1.X.X -> 2.0), large breaks in backwards @@ -97,12 +97,13 @@ The author of a SymPEP should fork the repository and create a draft pull request with a new SymPEP document based on the [SymPEP template](SymPEP-template). The SymPEP document may be named `SymPEP-XXXX.md` until a number is assigned. Once the author completes all information in the -template and would like it to be reviewed, one of the core SymPy developers should -decide if the proposal is a legtimate proposal and then assign a number to the -SymPEP, in which case `XXXX` should be replaced with the number with leading -0s. The pull request can then be moved to an open pull request and is ready for -community feedback and discussion but remains in draft state. The person who -assigns the number should also update the +template and would like it to be reviewed, one of the [core SymPy +developers](https://github.com/orgs/sympy/teams/developers-with-push-access-to-everything) +should decide if the proposal is a legitimate proposal and then assign a number +to the SymPEP, in which case `XXXX` should be replaced with the number with +leading 0s. The pull request can then be moved to an open pull request and is +ready for community feedback and discussion but remains in draft status. The +person who assigns the number should also update the [README](https://github.com/sympy/SymPEPs/blob/main/README.md) of the main [SymPEP repository](https://github.com/sympy/SymPEPs) to list that number. Numbers should be assigned to SymPEPs as soon as it is determined that they are @@ -113,11 +114,13 @@ number, as rejection or postponement status is still a discussion that should be documented in the SymPEP. SymPEP numbers should generally be assigned in increasing numeric order. -Discussion on the SymPEP should then continue on the open pull request. -Discussions may also take place in other places, such as [GitHub -discussions](https://github.com/sympy/SymPEPs/discussions) or the [mailing -list](http://groups.google.com/group/sympy). All discussions should be -cross-referenced in the "Discussions" section of the SymPEP document. +The author should announce the SymPEP on the mailing list when the number is +assigned to encourage discussion. Discussion on the SymPEP should primarily +continue on the open pull request but may also take place in other places, such +as [GitHub discussions](https://github.com/sympy/SymPEPs/discussions) or the +[mailing list](http://groups.google.com/group/sympy) with the later being +favored. All discussions should be cross-referenced in the "Discussions" +section of the SymPEP document. For each SymPEP, the community should decide whether a draft implementation of the change is needed before acceptance or not. For instance, if a SymPEP @@ -144,7 +147,7 @@ All SymPEPs should be created with the **Draft** status. **Draft** status SymPEPs generally live in a pull request. Eventually, after discussion, there may be a consensus that the SymPEP should -be accepted–see the next section for details. At this point the status becomes +be accepted; see the next section for details. At this point the status becomes **Accepted**. Once a SymPEP has been **Accepted**, the reference implementation must be @@ -194,12 +197,12 @@ In the body of your email, you should: - briefly describe any major points of contention and how they were resolved, -- include a sentence like: “If there are no substantive objections within 7 +- include a sentence like: "If there are no substantive objections within 7 days from this email, then the SymPEP will be accepted; see SymPEP 1 for more - details.” + details." -After you send the email, add the the email thread to the Discussion section of -the SymPEP, so that people can find it later. +After you send the email, add the email thread to the Discussion section of the +SymPEP, so that people can find it later. Generally the SymPEP author will be the one to send this email, but anyone can do it. The important thing is to make sure that everyone knows when a SymPEP is @@ -230,6 +233,32 @@ If there are substantive objections, then the SymPEP remains in Draft state, discussion continues as normal, and it can be proposed for acceptance again later once the objections are resolved. +## SymPEP Steps + +This describes the general set of steps for a SymPEP: + +- From a discussion in mailing list, issue or PR, someone might suggest a + SymPEP being needed. +- If discussion did not start on the mailing list, then move to the mailing + list (with cross-reference links) to gage whether a SymPEP is appropriate to + pursue. +- If it seems appropriate, make a draft pull request with your SymPEP. When your + draft is ready for a review, request a number assignment on the pull request. +- A core developer other than the author(s) assigns the number and opens the + pull request (out of Github draft state). +- Announce on the mailing list that the SymPEP is ready for review and + discussion. Suggest the primary forum for detailed discussion. +- Detailed discussion takes place in the designated forum until consensus of + those participating is reached. +- Once reached, announce the final draft of SymPEP on the mailing list and then + it can be 7 days or perhaps longer, if indicated, for anyone to object. +- After the objection period, the status of the SymPEP is set to "Accepted" and + a core developer merges the pull request. +- After implementation of the software changes or process changes, update the + SymPEP status to "Final". + +Deferment, rejection, or deemed inappropriate steps may occur along the way. + ## Discussion - [Initial mailing list post proposing diff --git a/SymPEP-template.md b/SymPEP-template.md index e9fb106..536a666 100644 --- a/SymPEP-template.md +++ b/SymPEP-template.md @@ -75,9 +75,8 @@ be discussed here, along with a justification for the chosen approach. ## Discussion This section may just be a bullet list including links to any discussions -regarding the SymPEP: - -- This includes links to mailing list threads or relevant GitHub issues. +regarding the SymPEP. All issues, pull requests, discussions, and mailing list +threads relating to a SymPEP should be listed and hyperlinked here. ## References From c1805e97a01c94cf05e636a5ff65ebb7ea81e108 Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Thu, 31 Aug 2023 13:10:39 +0200 Subject: [PATCH 08/16] Grammar. --- SymPEP-0001.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index 17ccd6d..310f804 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -237,8 +237,8 @@ later once the objections are resolved. This describes the general set of steps for a SymPEP: -- From a discussion in mailing list, issue or PR, someone might suggest a - SymPEP being needed. +- From a discussion in the mailing list, an issue or PR, someone might suggest + a SymPEP being needed. - If discussion did not start on the mailing list, then move to the mailing list (with cross-reference links) to gage whether a SymPEP is appropriate to pursue. From 1b5d58bb30fa7a0bd035f749efa7f4ba140f2667 Mon Sep 17 00:00:00 2001 From: Oscar Benjamin <oscar.j.benjamin@gmail.com> Date: Thu, 31 Aug 2023 12:11:10 +0100 Subject: [PATCH 09/16] Fix typo --- SymPEP-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index 310f804..493f778 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -118,7 +118,7 @@ The author should announce the SymPEP on the mailing list when the number is assigned to encourage discussion. Discussion on the SymPEP should primarily continue on the open pull request but may also take place in other places, such as [GitHub discussions](https://github.com/sympy/SymPEPs/discussions) or the -[mailing list](http://groups.google.com/group/sympy) with the later being +[mailing list](http://groups.google.com/group/sympy) with the latter being favored. All discussions should be cross-referenced in the "Discussions" section of the SymPEP document. From 1e0c36fc726e2e9f9c5ffc4f006625d6506cb36d Mon Sep 17 00:00:00 2001 From: Oscar Benjamin <oscar.j.benjamin@gmail.com> Date: Thu, 31 Aug 2023 12:11:43 +0100 Subject: [PATCH 10/16] Fix typo --- SymPEP-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index 493f778..79547bf 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -240,7 +240,7 @@ This describes the general set of steps for a SymPEP: - From a discussion in the mailing list, an issue or PR, someone might suggest a SymPEP being needed. - If discussion did not start on the mailing list, then move to the mailing - list (with cross-reference links) to gage whether a SymPEP is appropriate to + list (with cross-reference links) to gauge whether a SymPEP is appropriate to pursue. - If it seems appropriate, make a draft pull request with your SymPEP. When your draft is ready for a review, request a number assignment on the pull request. From a079ef528ee9a28ca3fc131fdf63dedf5c60c63d Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Thu, 31 Aug 2023 13:19:52 +0200 Subject: [PATCH 11/16] Update SymPEP-0001.md --- SymPEP-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index 79547bf..163adc8 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -183,7 +183,7 @@ isn't yet accepted or rejected. SymPEP discussions that have stalled should also be merged, so that the SymPEP becomes visible in the SymPEP repository proper—again, discussion may be picked up again with a new pull request. -## Accepting a SymPEP +### Accepting a SymPEP Once a SymPEP is Accepted by consensus of all interested contributors, an email should be sent to the [SymPy mailing From 80595001dea41ac2981138fc67ce2f5f5d58fb46 Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Thu, 31 Aug 2023 13:20:55 +0200 Subject: [PATCH 12/16] Update SymPEP-0001.md --- SymPEP-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index 163adc8..bee5d23 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -233,7 +233,7 @@ If there are substantive objections, then the SymPEP remains in Draft state, discussion continues as normal, and it can be proposed for acceptance again later once the objections are resolved. -## SymPEP Steps +### SymPEP Steps This describes the general set of steps for a SymPEP: From 3660d49a6e02d04a78ed5074e34062400e5e6fc4 Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Sat, 16 Sep 2023 08:46:34 +0200 Subject: [PATCH 13/16] Formal -> semi-formal. --- SymPEP-0001.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index bee5d23..e529a94 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -8,7 +8,7 @@ ## Abstract -SymPEPs are a formal process whereby important changes are proposed and +SymPEPs are a semi-formal process whereby important changes are proposed and discussed. Corresponding to each SymPEP is a document that outlines the proposed change(s), the discussion around those changes, and motivation for that change. This document outlines the details of the SymPEP process and @@ -16,7 +16,7 @@ corresponding documents. ## What is a SymPEP? -SymPEP stands for "SymPy Enhancement Proposal". SymPEPs represent a formal +SymPEP stands for "SymPy Enhancement Proposal". SymPEPs represent a semi-formal process whereby important changes are proposed and discussed in the SymPy community. Corresponding to each SymPEP is a SymPEP document which outlines the proposal and corresponding discussion. SymPEPs are based on the @@ -72,8 +72,8 @@ change. Discussions around a proposed change typically begin informally on the mailing list or SymPy issue/pull-request tracker. However, once it is decided that the -formal SymPEP process is desired for a change, the discussion should move to -the [SymPEP repository](https://github.com/sympy/SymPEPs) on GitHub. +SymPEP process is desired for a change, the discussion should move to the +[SymPEP repository](https://github.com/sympy/SymPEPs) on GitHub. Not all significant changes or additions to SymPy require a SymPEP. If the change would benefit from extended discussion or needs a roadmap for From 53d4200448c2c0099a6f70947960e7f5a0e1ccbc Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Sat, 16 Sep 2023 08:49:53 +0200 Subject: [PATCH 14/16] Should -> Could. --- SymPEP-0001.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index e529a94..fdc9ee1 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -61,12 +61,12 @@ The SymPEP process and corresponding documents serve several purposes: Importantly, **a SymPEP is not documentation** for the proposed change. End user documentation should be included with the implementation of the feature in the corresponding SymPy documentation. This also means that other documentation -should not rely on cross-referencing a SymPEP as if it were documentation for a -feature. Even technical discussion of a feature should be documented separately -from a SymPEP. The reason is that SymPEPs will necessarily include details that -are irrelevant to the final implementation, such as discussions of alternate -implementations which were rejected and discussions of implementation of the -change. +should not rely primarily on cross-referencing a SymPEP as if it were +documentation for a feature. Even technical discussion of a feature should be +documented separately from a SymPEP. The reason is that SymPEPs will +necessarily include details that are irrelevant to the final implementation, +such as discussions of alternate implementations which were rejected and +discussions of implementation of the change. ## SymPEP Workflow From 2e3ab476b1917ad457c3baf1b61cf6f3f0367714 Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Sat, 16 Sep 2023 08:54:37 +0200 Subject: [PATCH 15/16] Updated template for Oscar and Aaron's comments. --- SymPEP-template.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/SymPEP-template.md b/SymPEP-template.md index 536a666..9dfe3f0 100644 --- a/SymPEP-template.md +++ b/SymPEP-template.md @@ -3,7 +3,7 @@ SymPEP X — Template and Instructions **Author** list of authors' real names and optionally, email addresses **Status** Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded -**Type** Standards Track | Informational | Process +**Type** Standards Track | Process **Created** date created on, in yyyy-mm-dd format **Resolution** url to discussion (required for Accepted | Rejected | Withdrawn) @@ -117,9 +117,6 @@ Some extra notes about writing a SymPEP: The Markdown should be compatible with GitHub Flavored Markdown, so that the SymPEPs are viewable on GitHub. This means that Markdown features not supported by GitHub, such as footnotes, should be avoided. - <!-- XXX: Perhaps we should abandon this and only require them to be - readable in some rendered format. That would allow us to use MathJAX, which - could be useful. --> - Any references to other SymPEPs should be written as internal links, e.g., [SymPEP 1](SymPEP-0001). - Images or diagrams may be included in the SymPEP if they improve the @@ -133,3 +130,5 @@ Some extra notes about writing a SymPEP: possible. Note that images should only be included when they significantly improve the discussion in the SymPEP. The vast majority of SymPEPs should not include images. +- All sections in the template are not necessarily required, but are + encouraged. Including them will help you succeed with your proposal. From 7ecff5c3698d19d56a6df72b9b5e80553416c78b Mon Sep 17 00:00:00 2001 From: "Jason K. Moore" <moorepants@gmail.com> Date: Sun, 17 Sep 2023 10:31:53 +0200 Subject: [PATCH 16/16] Update SymPEP-0001.md --- SymPEP-0001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SymPEP-0001.md b/SymPEP-0001.md index fdc9ee1..3169024 100644 --- a/SymPEP-0001.md +++ b/SymPEP-0001.md @@ -1,7 +1,7 @@ # SymPEP 1 --- SymPEP Purpose and Process **Author** Aaron Meurer, Jason K. Moore -**Status** Draft +**Status** Accepted **Type** Process **Created** 2021-01-27 **Resolution**