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.
