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
