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.
