Can someone direct me to the places I need to change exactly, so I won't make mistakes in the PR?
On Mon, Feb 27, 2023 at 9:56 AM Enrico Olivelli <eolive...@gmail.com> wrote: > +1 great suggestions > > Enrico > > Il giorno lun 27 feb 2023 alle ore 02:54 <mattisonc...@gmail.com> ha > scritto: > > > > +1 > > > > Best, > > Mattison > > On Feb 26, 2023, 23:02 +0800, Dave Fisher <wave4d...@comcast.net>, > wrote: > > > Excellent proposal. > > > > > > Inline below. > > > > > > Sent from my iPhone > > > > > > > On Feb 26, 2023, at 3:19 AM, Asaf Mesika <asaf.mes...@gmail.com> > wrote: > > > > > > > > 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" > > > > > > Yes this is important as api and similar changes are what triggers > requiring small pips. > > > > > > > # 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. > > > > > > +1000! A Google doc hides details and obfuscates the design and > motivation. Google docs are not searchable within GitHub. > > > > > > We should reject all new PIPs that include Google Docs. > > > > > > Best, > > > Dave > > > > > > > > > > > # 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. > > > >
