Thanks for this initiative, Asaf. As part of this process, I would like for us to add a security and a multi-tenancy section to the PIP template.
As you suggest, the template conveys what the community values, and these two sections must always be considered when changing Pulsar in fundamental ways. (Thanks for already adding the security section to your template!) Thanks, Michael On Thu, Mar 16, 2023 at 2:58 AM Asaf Mesika <asaf.mes...@gmail.com> wrote: > > Here's the PR to remove the form and add a new issue template in Markdown > containing the suggested structure and description for each section. > > https://github.com/apache/pulsar/pull/19832 > > > On Wed, Mar 1, 2023 at 3:43 PM Elliot West > <elliot.w...@streamnative.io.invalid> wrote: > > > +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> > >
