Skip to content

Commit 033bcc7

Browse files
StevenLuMTliangyepianzhou
StevenLuMT
and
liangyepianzhou
authored
[improve][pcip] PCIP-1 Add the development process for pulsar-java-contrib project (apache#10)
* Add the development process * Update pcip/README.md Co-authored-by: Xiangying Meng <[email protected]> * Update pcip/README.md Co-authored-by: Xiangying Meng <[email protected]> * Update pcip/README.md Co-authored-by: Xiangying Meng <[email protected]> * Update pcip/README.md Co-authored-by: Xiangying Meng <[email protected]> * update some describe --------- Co-authored-by: nuolin <[email protected]> Co-authored-by: Xiangying Meng <[email protected]>
1 parent c15093e commit 033bcc7

File tree

4 files changed

+186
-0
lines changed

4 files changed

+186
-0
lines changed

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,10 @@ pulsar-java-contrib is actively in development. If you have some common use cas
2121
Please [open an issue](https://github.com/apache/pulsar-java-contrib/issues/new) to share your idea or
2222
suggestion. PRs are always welcome and greatly appreciated, but for larger functional changes a pre-coding introduction
2323
can be helpful to ensure this is the correct place and that active or conflicting efforts don't exist.
24+
25+
## Development Process
26+
Compared with [pulsar](https://github.com/apache/pulsar) , [pulsar-java-contrib](https://github.com/apache/pulsar-java-contrib) is faster, and there is no need to send emails for DISCUSSION and VOTE.
27+
it can be summarized as follows:
28+
1. for simple changes, you only need to submit a PR for code changes
29+
2. for larger improvement proposal, you need to submit a PR for code changes + a design document (the file is placed in pcip/pcip-xxx.md)
30+
For detailed development process description, see: pcip/README.md

‎pcip/README.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Pulsar Java Contrib Improvement Proposal (PCIP)
2+
3+
## What is a PCIP?
4+
5+
The PCIP is a "Pulsar Java Contrib Improvement Proposal" and it's the mechanism used to propose changes to the Apache Pulsar Java Contrib codebases.
6+
7+
The changes might be in terms of new features, large code refactoring.
8+
9+
In practical terms, the PCIP defines a process in which developers can submit a design doc, receive feedback and get the "go ahead" to execute.
10+
11+
12+
### What is the goal of a PCIP?
13+
14+
There are several goals for the PCIP process:
15+
16+
1. As a user manual, add instructions when introducing new features or modifying existing features.
17+
2. Explain the functional design ideas to facilitate review and later maintenance.
18+
19+
It is not a goal for PCIP to add undue process or slow-down the development.
20+
21+
### When is a PCIP required?
22+
23+
* Any new feature for Pulsar Java Contrib
24+
* Any change to the semantic of existing functionality
25+
* Any large code change that will touch multiple components
26+
* Any change to the configuration
27+
28+
### When is a PCIP *not* required?
29+
30+
* Bug-fixes
31+
* Documentation changes
32+
33+
### Who can create a PCIP?
34+
35+
Any person willing to contribute to the Apache Pulsar Java Contrib project is welcome to create a PCIP.
36+
37+
## How does the PCIP process work?
38+
39+
The process works in the following way:
40+
41+
1. Fork https://github.com/apache/pulsar-java-contrib repository (Using the fork button on GitHub).
42+
2. Clone the repository, and on it, copy the file `pcip/TEMPLATE.md` and name it `pcip-xxx.md`. The number `xxx` should be the next sequential number after the last contributed PCIP. You view the list of contributed PIPs (at any status) as a list of Pull Requests having a "PCIP" label. Use the link [here](https://github.com/apache/pulsar-java-contrib/pulls?q=is%3Apr+%22PCIP-%22+in%3Atitle+sort%3Acreated-desc) as shortcut.
43+
3. Write the proposal following the section outlined by the template and the explanation for each section in the comment it contains (you can delete the comment once done).
44+
* If you need the diagrams, please create a folder named pcip-XXX under the [pcip/static/img](https://github.com/apache/pulsar-java-contrib/tree/master/pcip/static/img) path and put the images in.
45+
4. Create GitHub Pull request (PR). The PR title should be `[improve][pcip] PCIP-xxx: {title}`, where the `xxx` match the number given in previous step (file-name). Replace `{title}` with a short title to your proposal.
46+
*Validate* again that your number does not collide, by step (2) numbering check.
47+
5. Based on the discussion and feedback, some changes might be applied by authors to the text of the proposal. They will be applied as extra commits, making it easier to track the changes.
48+
49+
To speed up the development process:
50+
1. you can put the code changes and design documents(pcip/pcip-xxx.md) in one PR.
51+
2. If the code is not yet developed, you can include only a design document(pcip/pcip-xxx.md) in the PR and submit the code separately after the development is completed.
52+
53+
## List of PCIPs
54+
55+
### Historical PCIPs
56+
You can the view list of PCIPs previously managed by GitHub [here](https://github.com/apache/pulsar-java-contrib/tree/master/pcip)
57+
58+
### List of PCIPs
59+
1. You can view all PCIPs (besides the historical ones) as the list of Pull Requests having title starting with `PCIP-`. Here is the [link](https://github.com/apache/pulsar-java-contrib/pulls?q=is%3Apr+%22PCIP-%22+in%3Atitle+sort%3Acreated-desc) for it.
60+
- Merged PR means the PCIP was accepted.
61+
- Closed PR means the PCIP was rejected.
62+
- Open PR means the PCIP was submitted and is in the process of discussion.
63+
2. You can also take a look at the file in the `pcip` folder. Each one is an approved PCIP.

‎pcip/TEMPLATE.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
<!--
2+
RULES
3+
* Never place a link to an external site like Google Doc. The proposal should be in this issue entirely.
4+
* Use a spelling and grammar checker tools if available for you (there are plenty of free ones).
5+
6+
PROPOSAL HEALTH CHECK
7+
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.
8+
9+
IMAGES
10+
If you need the diagrams, please create a folder named pcip-XXX under the [pcip/static/img](https://github.com/apache/pulsar-java-contrib/tree/master/pcip/static/img) path and put the images in.
11+
12+
THIS COMMENTS
13+
Please remove them when done.
14+
-->
15+
16+
# PCIP-XXX: Proposal title
17+
18+
# Background knowledge
19+
20+
<!--
21+
Describes all the knowledge you need to know in order to understand all the other sections in this PCIP
22+
23+
* 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.
24+
If you're going to change something specific, then go into more detail about it and how it works.
25+
* Provide links where possible if a person wants to dig deeper into the background information.
26+
27+
DON'T
28+
* Do not include links *instead* explanation. Do provide links for further explanation.
29+
30+
EXAMPLES
31+
* See [PCIP-2](https://github.com/apache/pulsar-java-contrib/pull/6), Background section to get an understanding on how you add the background knowledge needed.
32+
(They also included the motivation there, but ignore it as we place that in Motivation section explicitly).
33+
-->
34+
35+
# Motivation
36+
37+
<!--
38+
Describe the problem this proposal is trying to solve.
39+
40+
* Explain what is the problem you're trying to solve - current situation.
41+
* This section is the "Why" of your proposal.
42+
-->
43+
44+
# Goals
45+
46+
## In Scope
47+
48+
<!--
49+
What this PCIP intend to achieve once It's integrated into Pulsar.
50+
Why does it benefit Pulsar.
51+
-->
52+
53+
## Out of Scope
54+
55+
<!--
56+
Describe what you have decided to keep out of scope, perhaps left for a different PCIP/s.
57+
-->
58+
59+
60+
# High Level Design
61+
62+
<!--
63+
Describe the design of your solution in *high level*.
64+
Describe the solution end to end, from a birds-eye view.
65+
Don't go into implementation details in this section.
66+
67+
I should be able to finish reading from beginning of the PCIP to here (including) and understand the feature and
68+
how you intend to solve it, end to end.
69+
70+
DON'T
71+
* Avoid code snippets, unless it's essential to explain your intent.
72+
-->
73+
74+
# Detailed Design
75+
76+
## Design & Implementation Details
77+
78+
<!--
79+
This is the section where you dive into the details. It can be:
80+
* Concrete class names and their roles and responsibility, including methods.
81+
* Code snippets of existing code.
82+
* Interface names and its methods.
83+
* ...
84+
-->
85+
86+
## Public-facing Changes
87+
88+
<!--
89+
Describe the additions you plan to make for each public facing component.
90+
Remove the sections you are not changing.
91+
Clearly mark any changes which are BREAKING backward compatability.
92+
-->
93+
94+
### Public API
95+
<!--
96+
When adding a new endpoint to the REST API, please make sure to document the following:
97+
98+
* path
99+
* query parameters
100+
* HTTP body parameters, usually as JSON.
101+
* Response codes, and for each what they mean.
102+
For each response code, please include a detailed description of the response body JSON, specifying each field and what it means.
103+
This is the place to document the errors.
104+
-->
105+
106+
### Configuration
107+
108+
### CLI
109+
110+
# Get started
111+
112+
## Quick Start
113+
114+
<!--
115+
Introduce how to use it and teach users how to use it quickly
116+
-->

‎pcip/static/img/pcip-{xxx}/img-{xxx}.png‎

131 KB
Loading

0 commit comments

Comments
 (0)