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..947d531 --- /dev/null +++ b/pcip/README.md @@ -0,0 +1,65 @@ +# 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, even when current behavior is incorrect. +* Any large code change that will touch multiple components +* Any change to the configuration + +### When is a PCIP *not* required? + +* Bug-fixes +* Small documentation changes +* Small website changes +* Build scripts changes (except: a complete rewrite) + +### 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+label%3APCIP+) 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 `[improve][pcip] PCIP-`. Here is the [link](https://github.com/apache/pulsar-java-contrib/pulls?q=is%3Apr+title%3A%22%5Bpcip%5D%5Bdesign%5D+PCIP-%22) 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..01da888 --- /dev/null +++ b/pcip/TEMPLATE.md @@ -0,0 +1,165 @@ + + +# PCIP-XXX: Proposal title + +# Background knowledge + + + +# Motivation + + + +# Goals + +## In Scope + + + +## Out of Scope + + + + +# High Level Design + + + +# Detailed Design + +## Design & Implementation Details + + + +## Public-facing Changes + + + +### Public API + + +### Binary protocol + +### Configuration + +### CLI + +### Metrics + + + + +# Monitoring + + + +# Backward & Forward Compatibility + +## Upgrade + + + +## Downgrade / Rollback + + + +## Pulsar Geo-Replication Upgrade & Downgrade/Rollback Considerations + + + +# Alternatives + + + +# General Notes + +# Links + + +* Mailing List discussion thread: +* Mailing List voting thread: \ No newline at end of file diff --git a/pcip/static/img/pcip-{xxx}-img-{x}.png b/pcip/static/img/pcip-{xxx}-img-{x}.png new file mode 100644 index 0000000..0fbb7bb Binary files /dev/null and b/pcip/static/img/pcip-{xxx}-img-{x}.png differ