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> >>>
