+1 Asaf I'd also suggest that we encourage the submission of relevant diagrams. This is trivial to do with the GitHub markdown editor, but I suspect is often neglected because users do not know the feature exists.
On Wed, 1 Mar 2023 at 13:22, Asaf Mesika <asaf.mes...@gmail.com> wrote: > Ok. > > I'll draft a PR and link it here when I'm done. Thanks! > > On Tue, Feb 28, 2023 at 7:08 AM PengHui Li <peng...@apache.org> wrote: > > > +1 > > > > Penghui > > > > On Mon, Feb 27, 2023 at 9:24 PM Asaf Mesika <asaf.mes...@gmail.com> > wrote: > > > > > Mails don't support things like markdown diagrams or images and are > > > generally less easy to read. > > > My proposal includes a required section called Links in which you need > to > > > fill in the discussion thread in DEV mailing list and vote thread. > > > > > > > > > On Mon, Feb 27, 2023 at 3:08 PM Girish Sharma <scrapmachi...@gmail.com > > > > > wrote: > > > > > > > Hi Asaf, > > > > I was referring to the PIP process, as a whole, as explained in > > > > https://github.com/apache/pulsar/blob/master/wiki/proposals/PIP.md > > > > Someone looking at GitHub ticket would find and almost empty PIP GH > > issue > > > > while the same PIP has had many discussions over here in the ML. > > > > There is scope of improvement in the process where we either remove > the > > > > first step to create the PIP over at GitHub and directly present the > > PIP > > > in > > > > the first mail of the thread here, or we do all discussions in GH. > > > > Both the ML and GH are searchable and linkable for tracking purposes. > > > > > > > > Regards > > > > > > > > On Mon, Feb 27, 2023 at 6:23 PM Asaf Mesika <asaf.mes...@gmail.com> > > > wrote: > > > > > > > > > On Sun, Feb 26, 2023 at 2:49 PM Girish Sharma < > > scrapmachi...@gmail.com > > > > > > > > > wrote: > > > > > > > > > > > Good proposal Asaf. > > > > > > I've also wondered why the PIP creation and discussion process is > > so > > > > > > separated. The PIP discussion and voting starts off as a GitHub > > > issue, > > > > > but > > > > > > all of its discussion happens here on the mailing list. Is there > > > scope > > > > of > > > > > > improvement in that process as well? > > > > > > > > > > > > > > > > Not sure I follow. Can you outline the problem exactly? > > > > > > > > > > > > > > > > > > > > > > Regards > > > > > > > > > > > > On Sun, Feb 26, 2023 at 6:16 PM tison <ti...@apache.org> wrote: > > > > > > > > > > > > > Hi Asaf, > > > > > > > > > > > > > > I agree that, generally, a PIP is written as a whole and paste > as > > > the > > > > > > body. > > > > > > > So +1 for your proposal. > > > > > > > > > > > > > > Additionally, I'm thinking of moving the doc of procedure > > > > (wiki/PIP.md) > > > > > > to > > > > > > > the contributions guide and use the new markdown template to > > > > supersede > > > > > > the > > > > > > > wiki/PIP-template.md. Then we don't need to hold the wiki > folder. > > > > > > > > > > > > > > It can be an extended version to your proposal, so let's keep > on > > > your > > > > > > > proposal in this thread. Just for your reference. > > > > > > > > > > > > > > Best, > > > > > > > tison. > > > > > > > > > > > > > > > > > > > > > Asaf Mesika <asaf.mes...@gmail.com> 于2023年2月26日周日 19:18写道： > > > > > > > > > > > > > > > Hi, > > > > > > > > > > > > > > > > I would like to suggest two changes I'd like to make to the > PIP > > > > > design > > > > > > > > template: > > > > > > > > 1. Remove the form - just have a markdown template fill the > > issue > > > > > body > > > > > > as > > > > > > > > it is created. > > > > > > > > 2. Change the PIP template structure > > > > > > > > > > > > > > > > == Removing the form > > > > > > > > > > > > > > > > Today, when you want to submit a PIP, you are required to > fill > > > out > > > > a > > > > > > form > > > > > > > > with boxes composed of 3-4 lines length. > > > > > > > > It's not good because: > > > > > > > > * It broadcasts to the author: we want a very small PIP, > > > something > > > > > that > > > > > > > > fits those small boxes. > > > > > > > > * It makes the PIP look like a bug, where you fill out > fields. > > > > > > > > * It doesn't allow having H2 headings, only H1 headings, thus > > > > > limiting > > > > > > > the > > > > > > > > structure. > > > > > > > > > > > > > > > > A PIP is a design essentially, something 1-3 pages long. > Thus, > > > > > > > > people take the time to write it down. Preferably, they copy > > > paste > > > > > the > > > > > > > body > > > > > > > > of the PIP issue, and use it to fill in sections. > > > > > > > > > > > > > > > > My suggestion is to define an issue template using only > > markdown, > > > > > > > without a > > > > > > > > form. > > > > > > > > > > > > > > > > == Changing PIP Structure > > > > > > > > > > > > > > > > Today the structure of the PIP doc (pasted below), is > missing a > > > > > section > > > > > > > and > > > > > > > > generally aims to jump directly into API changes / code / > > > > > > implementation. > > > > > > > > This results in lots of back and forth emails in an attempt > to > > > get > > > > > the > > > > > > > > following essentials: > > > > > > > > * All required background knowledge to understand the > proposal > > > > > > > > * A high level overview of the proposed solution > > > > > > > > * Understanding how this proposal will be monitored > > > > > > > > * What steps exactly I need to take if I revert to the > previous > > > > > > version. > > > > > > > > > > > > > > > > The structure I propose below aims to reduce that friction > and > > > get > > > > > all > > > > > > > PIP > > > > > > > > aligned to provide that information. > > > > > > > > > > > > > > > > === Today's structure > > > > > > > > > > > > > > > > # Motivation > > > > > > > > * "Explain why this change is needed, what benefits it would > > > bring > > > > to > > > > > > > > Apache Pulsar and what problem it's trying to solve." > > > > > > > > # Goal > > > > > > > > * "Define the scope of this proposal. Given the motivation > > stated > > > > > > above, > > > > > > > > what are the problems that this proposal is addressing and > what > > > > other > > > > > > > items > > > > > > > > will be considering out of scope, perhaps to be left to a > > > different > > > > > > PIP." > > > > > > > > # API Changes > > > > > > > > * "Illustrate all the proposed changes to the API or wire > > > protocol, > > > > > > with > > > > > > > > examples of all the newly added classes/methods, including > > > Javadoc" > > > > > > > > # Implementation > > > > > > > > * "This should be a detailed description of all the changes > > that > > > > are > > > > > > > > expected to be made. It should be detailed enough that any > > > > developer > > > > > > that > > > > > > > > is familiar with Pulsar internals would be able to understand > > all > > > > the > > > > > > > parts > > > > > > > > of the code changes for this proposal." > > > > > > > > * "This should also serve as documentation for any person > that > > is > > > > > > trying > > > > > > > to > > > > > > > > understand or debug the behavior of a certain feature." > > > > > > > > # Alernatives > > > > > > > > * "If there are alternatives that were already considered by > > the > > > > > > authors > > > > > > > > or, after the discussion, by the community, and were > rejected, > > > > please > > > > > > > list > > > > > > > > them here along with the reason why they were rejected" > > > > > > > > # Anything else? > > > > > > > > > > > > > > > > > > > > > > > > === My suggestion > > > > > > > > > > > > > > > > # Motivation and Background information > > > > > > > > * Give a high level explanation on all concepts you will be > > using > > > > > > > > throughout this document. For example, if you want to talk > > about > > > > > > > Persistent > > > > > > > > Subscriptions, explain briefly (1 paragraph) what this is. If > > > > you're > > > > > > > going > > > > > > > > to talk about Transaction Buffer, explain briefly what this > is. > > > If > > > > > > you're > > > > > > > > going to change something specific, that goes into a bit more > > > > detail > > > > > > > about > > > > > > > > it and how it works. The Litmus test: I can read the design > > > > document > > > > > > and > > > > > > > > understand the problem statement and what you plan to change > > > > > *without* > > > > > > > > resorting to a couple of hours of code reading just to start > > > > having a > > > > > > > high > > > > > > > > level understanding of the change. > > > > > > > > * Provide links where possible if a person wants to dig > deeper > > > into > > > > > the > > > > > > > > background information. > > > > > > > > * Explain what is the problem you're trying to solve - > current > > > > > > situation. > > > > > > > > * This section is the "Why" of your proposal. > > > > > > > > > > > > > > > > # Goals > > > > > > > > ## Scope > > > > > > > > * Describe the goals of your proposal, and why it benefits > > Apache > > > > > > Pulsar > > > > > > > > ## Out of Scope > > > > > > > > * Describe what you have decided to keep out of scope, > perhaps > > > left > > > > > > for a > > > > > > > > different PIP/s. > > > > > > > > > > > > > > > > # High-level Design > > > > > > > > * Describe in high level, end-to-end, the solution. This > should > > > be > > > > a > > > > > > few > > > > > > > > paragraphs long as a guideline. > > > > > > > > * Reading this would allow me to understand the solution > from a > > > > > bird's > > > > > > > eye > > > > > > > > view, end to end. > > > > > > > > * DON'T put all the design in a Google Doc and share the link > > > here, > > > > > as > > > > > > it > > > > > > > > won't last the test of time. > > > > > > > > > > > > > > > > # Detailed Design > > > > > > > > * Describe in detail what you plan to do to achieve your high > > > level > > > > > > > design > > > > > > > > * It should include the following if applicable: > > > > > > > > * REST API Changes > > > > > > > > * Protocol Changes > > > > > > > > > > > > > > > > # Monitoring > > > > > > > > * Describe exactly what you will add to Pulsar allowing you > to > > > > > > > > monitor/observe this proposal? > > > > > > > > * If those are metrics, provide the names, description, > > labels > > > > and > > > > > > > units > > > > > > > > * Explain what constitutes abnormal that I should pay > > attention > > > > to > > > > > > > > > > > > > > > > # Backward Compatibility > > > > > > > > * Describe exact instructions if someone needs to revert > from a > > > > > version > > > > > > > > containing it to a previous version > > > > > > > > > > > > > > > > # Alternatives > > > > > > > > * Describe alternative design decisions and why you have not > > > opted > > > > > for > > > > > > > them > > > > > > > > > > > > > > > > # General notes > > > > > > > > * Any general notes you wish to make > > > > > > > > > > > > > > > > # Links (Updated afterwards) > > > > > > > > * Mailing List discussion thread: > > > > > > > > * Mailing List voting thread: > > > > > > > > > > > > > > > > == > > > > > > > > Would love to hear what you think about it, before opening a > PR > > > > about > > > > > > > this. > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > > Girish Sharma > > > > > > > > > > > > > > > > > > > > > > > -- > > > > Girish Sharma > > > > > > > > > > -- Elliot West Senior Platform Engineer elliot.w...@streamnative.io streamnative.io <https://github.com/streamnative> <https://www.linkedin.com/company/streamnative> <https://twitter.com/streamnativeio>
