Skip to content

Commit

Permalink
[Process] Added the RFC template docs [delta-io#2594] (delta-io#2601)
Browse files Browse the repository at this point in the history
* Added the RFC template docs
  • Loading branch information
tdas authored Feb 7, 2024
1 parent bfc652a commit e7959fe
Show file tree
Hide file tree
Showing 3 changed files with 110 additions and 0 deletions.
29 changes: 29 additions & 0 deletions .github/ISSUE_TEMPLATE/protocol-rfc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@

---
name: Protocol Change Request
about: Use this template to propose a new feature that impacts the Delta protocol specification
labels: 'protocol'
title: '[PROTOCOL RFC]'

---

## Protocol Change Request

### Description of the protocol change

<!--
Please describe the motivation and high-level description of the protocol change you are proposing.
For a fairly large protocol change, it is recommended that you provide a design doc - (e.g., a google doc, preferably with the ability to comment in the doc).
For the next steps on how to proceed with the request, see the protocol RFC process in https://github.com/delta-io/delta/tree/master/protocol_rfcs
-->


### Willingness to contribute

The Delta Lake Community encourages protocol innovations. Would you or another member of your organization be willing to contribute this feature to the Delta Lake code base?

- [ ] Yes. I can contribute.
- [ ] Yes. I would be willing to contribute with guidance from the Delta Lake community.
- [ ] No. I cannot contribute at this time.


70 changes: 70 additions & 0 deletions protocol_rfcs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Protocol RFCs

This directory contains information about the process of making Delta protocol changes via RFCs and all the RFCs that have been proposed since
this process was adopted.

- [Table of RFCs](#table-of-rfcs)
- [Proposed RFCs](#proposed-rfcs)
- [Accepted RFCs](#accepted-rfcs)
- [Rejected RFCs](#rejected-rfcs)
- [RFC Process](#rfc-process)


## Table of RFCs

Here is the history of all the RFCs propose/accepted/rejected since Feb 6, 2024, when this process was introduced.

### Proposed RFCs

| Date proposed | RFC file | Github issue | RFC title |
|:-|:-|:-|:-|
| 2023-02-05 | [my_table_feature.md](https://github.com/delta-io/delta/blob/master/protocol_rfcs/my_table_feature.md) | https://github.com/delta-io/delta/issues/XXXX | My Table Feature | <!-- remove this when adding the first RFC -->
|...|||||

### Accepted RFCs

| Date proposed | Date accepted | RFC file | Github issue | RFC title |
|:-|:-|:-|:-|:-|
|...|||||

### Rejected RFCs

| Date proposed | Date rejected | RFC file | Github issue | RFC title |
|:-|:-|:-|:-|:-|
|...|||||


## RFC process

### **1. Make initial proposal**
Create a Github issue of type [Protocol Change Request].
- The description of the issue may have links to design docs, etc.
- This issue will serve as the central location for all discussions related to the protocol change.
- If the proposal comes with a prototype or other pathfinding, the changes should be in an open PR.

### **2. Add the RFC doc**
After creating the issue and discussing with the community, if a basic consensus is reached that this feature should be implemented, then create a PR to add the protocol RFC before merging code in master.
- Clone the RFC template `template.md` and create a new RFC markdown doc.
- Cross-link with the issue with "see #xxx". DONT USE "closes #xxx" or "fixes #xxx" or "resolves #xxx" because we don't want the issue to be closed when this RFC PR is merged.

Note:
- For table features, it is strongly recommended that any experimental support for the feature uses a temporary feature name with a suffix like `-dev`. This will communicate to the users that are about to use experimental feature with no future compatibility guarantee.
- Code related to a proposed feature should not be merged into the main branch until the RFC attains "proposed" status (that is, the RFC PR has been through public review and merged). Until the RFC has been accepted (that is, the proposed changes have been merged into the Delta specification), any code changes should be isolated from production code behind feature flags, etc. so that existing users are not affected in any way.

### **3. Finally, accept or reject the RFC**
For a RFC to be accepted, it must satisfy the following criteria:
- There is a production implementation (for example, in delta-spark) of the feature that has been thoroughly well tested.
- There is at least some discussion and/or prototype (preferred) that ensure the feasibility of the feature in Delta Kernel.

When the success criteria are met, then the protocol can be finalized by making a PR to make the following changes:
- Closely validate that the protocol spec changes are actually consistent with the production implementation.
- Cross-link the PR with the original issue with "closes #xxx" as now we are ready to close the issue. In addition, update the title of the issue to say `[ACCEPTED]` to make it obvious how the proposal was resolved.
- Update `protocol.md`.
- Move the RFC doc to the `accepted` subdirectory, and update the state in index.md.
- Remove the temporary/preview suffix like `-dev` in the table feature name from all the code.

However, if the RFC is to be rejected, then make a PR to do the following changes:
- Cross-link the PR with the original issue with "closes #xxx" as now we are ready to close the issue. In addition, update the title of the issue to say `[REJECTED]` to make it obvious how the proposal was resolved.
- Move the RFC doc to the `rejected` subdirectory.
- Update the state in `index.md`.
- Remove any experimental/preview code related to the feature.
11 changes: 11 additions & 0 deletions protocol_rfcs/template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Table feature name / meaningful name
**Associated Github issue for discussions: https://github.com/delta-io/delta/issues/XXXX**
<!-- Remove this: Replace XXXX with the actual github issue number -->


<!-- Give a general description / context of the protocol change, and remove this comment. -->

--------

<!-- Remove this: Add your proposed protocol.md modifications here, and remove this comment. -->

0 comments on commit e7959fe

Please sign in to comment.