Skip to content

Commit 3d0eb6f

Browse files
authored
Update README.md
integrated review feedback
1 parent ae98d5d commit 3d0eb6f

File tree

1 file changed

+19
-15
lines changed

1 file changed

+19
-15
lines changed

proposals/README.md

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,38 @@
11
# Proposals
22

3-
## Requirements
4-
5-
See the [requirements document](https://docs.google.com/document/d/1qGDnOyoNyPvcN4FCRhbZGAvp0SfewlWo-WVsai5IKUo/edit?tab=t.0#heading=h.v4emiipkghrx) (Note: this doc would become a markdown page in the repo)
3+
This proposal process is intended for significantly impactfull additions to the Parquet spec. The goal is to facilitate those projects and help them being contributed to Parquet.
4+
For example, changes that are not backward compatible like adding a new encoding or a new compression algorithm (older implementations can not read new files).
5+
This gives better visibility to those projects which require coordination in several implementations.
6+
Bug fixes, code only features or minor changes to the spec that can be ignored by older implementations can simply be filed as a github issue.
67

78
## Proposal lifecycle
89

9-
Discuss -> Draft -> POC -> Approved -> Implementation -> Release
10+
Discuss -> Draft/POC -> Implementation -> Release
1011

1112
### Discuss
12-
Start a [DISCUSS] thread on the mailing list (dev@parquet.apache.org) with your idea.
13-
Once you have a better idea of the direction, open a github issue using the proposal template.
14-
You can attach a google doc to collaborate on the general idea with the community.
13+
Start a [DISCUSS] thread on the mailing list (dev@parquet.apache.org) with your idea. At this point, the community can discuss whether the impact of the proposal requires a document here or just be a github issue.
14+
Once you have a better idea of the general consensus on the proposal, open a github issue using the proposal template.
15+
Attaching a google doc to collect feedback and collaborate with the community works usually well early on.
1516

16-
### Draft
17-
Once the discussion has stabilized and you are ready to start a POC, open a PR to add a new Markdown file in the proposals folder and give more visibility to the work in progress.
17+
*Transition:* Once you feel you received enough feedback or need to start the POC to have better answers to questions you get, you can move to the next step. Anybody is free to start POCs anytime. We just recommend getting feedback before you spend a significant amount of your time.
1818

19-
### POC
19+
### Draft/POC
20+
Once you feel the discussion has stabilized and you are ready to start a POC, open a PR to add a new Markdown file in the proposals folder and give more visibility to the work in progress.
2021
The proposal document can evolve along the course of the POC. In particular to add more links to findings and performance evaluations. Collaboration is encouraged. More validation on the POC increases the chances of success.
2122

22-
Make sure you consider the [#Requirements] to ensure the success of the POC.
23+
Make sure you consider the [requirements document](https://docs.google.com/document/d/1qGDnOyoNyPvcN4FCRhbZGAvp0SfewlWo-WVsai5IKUo/edit?tab=t.0#heading=h.v4emiipkghrx) to ensure the success of the POC. (Note: this doc would become a markdown page in the repo)
2324

24-
### Approved for Implementation
25-
Once the POC has concluded, we should have a clear idea of whether we want to pursue the implementation accross the ecosystem. A PMC vote will formalize that stage
25+
*Transition:* There is enough clarity on the spec for the new feature and we have identified the reference implementations to be implemented to be able to release.
2626

2727
### Implementation
28-
At this stage we need to meet the contribution guidelines to confsider the implementation finished (ex: two independent implementations with cross compatibility tests, spec updated, ...)
28+
Once we have reached enough consensus on the formalized spec change and validated it through the POC, we should have a clear idea of whether we want to pursue the implementation accross the ecosystem.
29+
At this stage we should finalize a formal spec contribution to parquet-format and we need to meet the contribution guidelines to consider the implementation finished.
30+
See [CONTRIBUTING guidelines](https://github.com/apache/parquet-format/blob/master/CONTRIBUTING.md#additionschanges-to-the-format).
31+
32+
*Transition:* A PMC vote will formalize that we have concluded the implementation and are ready to release.
2933

3034
### Release
31-
Once the implementation phase is finished, we can include the contribution in the next release.
35+
Once the implementation phase is finished, we can include the contribution in the next release. Congrats!
3236

3337
## Active Proposals
3438

0 commit comments

Comments
 (0)