This is an automated email from the ASF dual-hosted git repository.
xiangying pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-java-contrib.git
The following commit(s) were added to refs/heads/main by this push:
new 033bcc7 [improve][pcip] PCIP-1 Add the development process for
pulsar-java-contrib project (#10)
033bcc7 is described below
commit 033bcc7cf2f4f3ea4a91b642669bd11abd1dea6f
Author: StevenLuMT <[email protected]>
AuthorDate: Tue Nov 19 19:35:07 2024 +0800
[improve][pcip] PCIP-1 Add the development process for pulsar-java-contrib
project (#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]>
---
README.md | 7 ++
pcip/README.md | 63 +++++++++++++++++
pcip/TEMPLATE.md | 116 +++++++++++++++++++++++++++++++
pcip/static/img/pcip-{xxx}/img-{xxx}.png | Bin 0 -> 134377 bytes
4 files changed, 186 insertions(+)
diff --git a/README.md b/README.md
index af11647..110d1d3 100644
--- a/README.md
+++ b/README.md
@@ -21,3 +21,10 @@ pulsar-java-contrib is actively in development. If you have
some common use cas
Please [open an
issue](https://github.com/apache/pulsar-java-contrib/issues/new) to share your
idea or
suggestion. PRs are always welcome and greatly appreciated, but for larger
functional changes a pre-coding introduction
can be helpful to ensure this is the correct place and that active or
conflicting efforts don't exist.
+
+## Development Process
+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.
+it can be summarized as follows:
+1. for simple changes, you only need to submit a PR for code changes
+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)
+For detailed development process description, see: pcip/README.md
\ No newline at end of file
diff --git a/pcip/README.md b/pcip/README.md
new file mode 100644
index 0000000..9de355a
--- /dev/null
+++ b/pcip/README.md
@@ -0,0 +1,63 @@
+# Pulsar Java Contrib Improvement Proposal (PCIP)
+
+## What is a PCIP?
+
+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.
+
+The changes might be in terms of new features, large code refactoring.
+
+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.
+
+
+### What is the goal of a PCIP?
+
+There are several goals for the PCIP process:
+
+1. As a user manual, add instructions when introducing new features or
modifying existing features.
+2. Explain the functional design ideas to facilitate review and later
maintenance.
+
+It is not a goal for PCIP to add undue process or slow-down the development.
+
+### When is a PCIP required?
+
+* Any new feature for Pulsar Java Contrib
+* Any change to the semantic of existing functionality
+* Any large code change that will touch multiple components
+* Any change to the configuration
+
+### When is a PCIP *not* required?
+
+* Bug-fixes
+* Documentation changes
+
+### Who can create a PCIP?
+
+Any person willing to contribute to the Apache Pulsar Java Contrib project is
welcome to create a PCIP.
+
+## How does the PCIP process work?
+
+The process works in the following way:
+
+1. Fork https://github.com/apache/pulsar-java-contrib repository (Using the
fork button on GitHub).
+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.
+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).
+ * 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.
+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.
+ *Validate* again that your number does not collide, by step (2) numbering
check.
+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.
+
+To speed up the development process:
+1. you can put the code changes and design documents(pcip/pcip-xxx.md) in one
PR.
+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.
+
+## List of PCIPs
+
+### Historical PCIPs
+You can the view list of PCIPs previously managed by GitHub
[here](https://github.com/apache/pulsar-java-contrib/tree/master/pcip)
+
+### List of PCIPs
+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.
+ - Merged PR means the PCIP was accepted.
+ - Closed PR means the PCIP was rejected.
+ - Open PR means the PCIP was submitted and is in the process of discussion.
+2. You can also take a look at the file in the `pcip` folder. Each one is an
approved PCIP.
\ No newline at end of file
diff --git a/pcip/TEMPLATE.md b/pcip/TEMPLATE.md
new file mode 100644
index 0000000..0b4f294
--- /dev/null
+++ b/pcip/TEMPLATE.md
@@ -0,0 +1,116 @@
+<!--
+RULES
+* Never place a link to an external site like Google Doc. The proposal should
be in this issue entirely.
+* Use a spelling and grammar checker tools if available for you (there are
plenty of free ones).
+
+PROPOSAL HEALTH CHECK
+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.
+
+IMAGES
+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.
+
+THIS COMMENTS
+Please remove them when done.
+-->
+
+# PCIP-XXX: Proposal title
+
+# Background knowledge
+
+<!--
+Describes all the knowledge you need to know in order to understand all the
other sections in this PCIP
+
+* 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, then go into more detail about
it and how it works.
+* Provide links where possible if a person wants to dig deeper into the
background information.
+
+DON'T
+* Do not include links *instead* explanation. Do provide links for further
explanation.
+
+EXAMPLES
+* 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.
+ (They also included the motivation there, but ignore it as we place that in
Motivation section explicitly).
+-->
+
+# Motivation
+
+<!--
+Describe the problem this proposal is trying to solve.
+
+* Explain what is the problem you're trying to solve - current situation.
+* This section is the "Why" of your proposal.
+-->
+
+# Goals
+
+## In Scope
+
+<!--
+What this PCIP intend to achieve once It's integrated into Pulsar.
+Why does it benefit Pulsar.
+-->
+
+## Out of Scope
+
+<!--
+Describe what you have decided to keep out of scope, perhaps left for a
different PCIP/s.
+-->
+
+
+# High Level Design
+
+<!--
+Describe the design of your solution in *high level*.
+Describe the solution end to end, from a birds-eye view.
+Don't go into implementation details in this section.
+
+I should be able to finish reading from beginning of the PCIP to here
(including) and understand the feature and
+how you intend to solve it, end to end.
+
+DON'T
+* Avoid code snippets, unless it's essential to explain your intent.
+-->
+
+# Detailed Design
+
+## Design & Implementation Details
+
+<!--
+This is the section where you dive into the details. It can be:
+* Concrete class names and their roles and responsibility, including methods.
+* Code snippets of existing code.
+* Interface names and its methods.
+* ...
+-->
+
+## Public-facing Changes
+
+<!--
+Describe the additions you plan to make for each public facing component.
+Remove the sections you are not changing.
+Clearly mark any changes which are BREAKING backward compatability.
+-->
+
+### Public API
+<!--
+When adding a new endpoint to the REST API, please make sure to document the
following:
+
+* path
+* query parameters
+* HTTP body parameters, usually as JSON.
+* Response codes, and for each what they mean.
+ For each response code, please include a detailed description of the
response body JSON, specifying each field and what it means.
+ This is the place to document the errors.
+-->
+
+### Configuration
+
+### CLI
+
+# Get started
+
+## Quick Start
+
+<!--
+Introduce how to use it and teach users how to use it quickly
+-->
\ No newline at end of file
diff --git a/pcip/static/img/pcip-{xxx}/img-{xxx}.png
b/pcip/static/img/pcip-{xxx}/img-{xxx}.png
new file mode 100644
index 0000000..0fbb7bb
Binary files /dev/null and b/pcip/static/img/pcip-{xxx}/img-{xxx}.png differ
