So far only 1 PMC member reviewed it. Any other PMC member would like to review the new template for PIP?
On Wed, Mar 22, 2023 at 1:10 PM Asaf Mesika <asaf.mes...@gmail.com> wrote: > Any other PMC member can take a look at the new template PR > <https://github.com/apache/pulsar/pull/19832>? > Ideally I would like to have 2-3 PMC member approval for this. > > > On 17 Mar 2023, at 18:23, Michael Marshall <mmarsh...@apache.org> wrote: > > 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> > > >
