From 68ad31c25beeca952a99131afff6ca232432f9ba Mon Sep 17 00:00:00 2001 From: Nicholas Bollweg Date: Tue, 14 Mar 2023 18:26:34 -0500 Subject: [PATCH] start with template --- .../text-based-diagrams.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 xx-text-based-diagrams-in-markdown/text-based-diagrams.md diff --git a/xx-text-based-diagrams-in-markdown/text-based-diagrams.md b/xx-text-based-diagrams-in-markdown/text-based-diagrams.md new file mode 100644 index 00000000..5ce71610 --- /dev/null +++ b/xx-text-based-diagrams-in-markdown/text-based-diagrams.md @@ -0,0 +1,84 @@ +--- +title: +authors: +issue-number: +pr-number: +date-started: +--- + +# Summary + +One paragraph explanation of the proposal. + +# Motivation + +Why are we doing this? What use cases does it support? What is the expected outcome? + +# Guide-level explanation + +Explain the proposal as if it was already implemented and you were +explaining it to another community member. That generally means: + +- Introducing new named concepts. +- Adding examples for how this proposal affects people's experience. +- Explaining how others should *think* about the feature, and how it should impact the experience using Jupyter tools. It should explain the impact as concretely as possible. +- If applicable, provide sample error messages, deprecation warnings, or migration guidance. +- If applicable, describe the differences between teaching this to existing Jupyter members and new Jupyter members. + +For implementation-oriented JEPs, this section should focus on how other Jupyter +developers should think about the change, and give examples of its concrete impact. For policy JEPs, this section should provide an example-driven introduction to the policy, and explain its impact in concrete terms. + +# Reference-level explanation + +This is the technical portion of the JEP. Explain the design in +sufficient detail that: + +- Its interaction with other features is clear. +- It is reasonably clear how the feature would be implemented. +- Corner cases are dissected by example. + +The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work. + +# Rationale and alternatives + +- Why is this choice the best in the space of possible designs? +- What other designs have been considered and what is the rationale for not choosing them? +- What is the impact of not doing this? + +# Prior art + +Discuss prior art, both the good and the bad, in relation to this proposal. +A few examples of what this can include are: + +- Does this feature exist in other tools or ecosystems, and what experience have their community had? +- For community proposals: Is this done by some other community and what were their experiences with it? +- For other teams: What lessons can we learn from what other communities have done here? +- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background. + +This section is intended to encourage you as an author to think about the lessons from other languages, provide readers of your JEP with a fuller picture. +If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other languages. + + +# Unresolved questions + +- What parts of the design do you expect to resolve through the JEP process before this gets merged? +- What related issues do you consider out of scope for this JEP that could be addressed in the future independently of the solution that comes out of this JEP? + +# Future possibilities + +Think about what the natural extension and evolution of your proposal would +be and how it would affect the Jupyter community at-large. Try to use this section as a tool to more fully consider all possible +interactions with the project and language in your proposal. +Also consider how the this all fits into the roadmap for the project +and of the relevant sub-team. + +This is also a good place to "dump ideas", if they are out of scope for the +JEP you are writing but otherwise related. + +If you have tried and cannot think of any future possibilities, +you may simply state that you cannot think of anything. + +Note that having something written down in the future-possibilities section +is not a reason to accept the current or a future JEP; such notes should be +in the section on motivation or rationale in this or subsequent JEPs. +The section merely provides additional information.