Skip to content

Commit c5738d6

Browse files
author
John Plaisted
authored
Add documentation around the DataHub RFC process. (#1754)
Other repos have similar RFC processes (though they seem to have a separate repo for their RFC docs). This provides a more structured way for contributors to make siginficant design contributions. #1692
1 parent 80f7770 commit c5738d6

File tree

4 files changed

+195
-0
lines changed

4 files changed

+195
-0
lines changed

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ DataHub is LinkedIn's generalized metadata search & discovery tool. To learn mor
1313
* [Generalized Metadata Service](https://github.com/linkedin/datahub/tree/master/gms)
1414
* [Metadata Ingestion](https://github.com/linkedin/datahub/tree/master/metadata-ingestion)
1515
* [Metadata Processing Jobs](https://github.com/linkedin/datahub/tree/master/metadata-jobs)
16+
* [The RFC Process](rfc.md)

‎docs/rfc.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# DataHub RFC
2+
3+
## What is an RFC?
4+
5+
The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features,
6+
significant modifications, or any other significant proposal to enter DataHub and its related frameworks.
7+
8+
Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub
9+
pull request workflow.
10+
11+
Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a
12+
consensus among the DataHub core teams.
13+
14+
## The RFC life-cycle
15+
16+
An RFC goes through the following stages:
17+
18+
- *Discussion* (Optional): Create an issue with the "RFC" label to have a more open ended, initial discussion around
19+
your proposal (useful if you don't have a concrete proposal yet). Consider posting to #rfc in [Slack](../slack.md)
20+
for more visibility.
21+
- *Pending*: when the RFC is submitted as a PR. Please add the "RFC" label to the PR.
22+
- *Active*: when an RFC PR is merged and undergoing implementation.
23+
- *Landed*: when an RFC's proposed changes are shipped in an actual release.
24+
- *Rejected*: when an RFC PR is closed without being merged.
25+
26+
[Pending RFC List](https://github.com/linkedin/datahub/pulls?q=is%3Apr+is%3Aopen+label%3Arfc+)
27+
28+
## When to follow this process
29+
30+
You need to follow this process if you intend to make "substantial" changes to any components in the DataHub git repo,
31+
their documentation, or any other projects under the purview of the DataHub core teams. What constitutes a "substantial"
32+
change is evolving based on community norms, but may include the following:
33+
34+
- A new feature that creates new API surface area, and would require a feature flag if introduced.
35+
- The removal of features that already shipped as part of the release channel.
36+
- The introduction of new idiomatic usage or conventions, even if they do not include code changes to DataHub itself.
37+
38+
Some changes do not require an RFC:
39+
40+
- Rephrasing, reorganizing or refactoring
41+
- Addition or removal of warnings
42+
- Additions that strictly improve objective, numerical quality criteria (speedup)
43+
44+
If you submit a pull request to implement a new, major feature without going through the RFC process, it may be closed
45+
with a polite request to submit an RFC first.
46+
47+
## Gathering feedback before submitting
48+
49+
It's often helpful to get feedback on your concept before diving into the level of API design detail required for an
50+
RFC. You may open an issue on this repo to start a high-level discussion, with the goal of eventually formulating an RFC
51+
pull request with the specific implementation design. We also highly recommend sharing drafts of RFCs in #rfc on the
52+
[DataHub Slack](../slack.md) for early feedback.
53+
54+
## The process
55+
56+
In short, to get a major feature added to DataHub, one must first get the RFC merged into the RFC repo as a markdown
57+
file. At that point the RFC is 'active' and may be implemented with the goal of eventual inclusion into DataHub.
58+
59+
- Fork the DataHub repository.
60+
- Copy the `000-template.md` template file to `docs/rfcs/active/000-my-feature.md`, where `my-feature` is more
61+
descriptive. Don't assign an RFC number yet.
62+
- Fill in the RFC. Put care into the details. *RFCs that do not present convincing motivation, demonstrate understanding
63+
of the impact of the design, or are disingenuous about the drawback or alternatives tend to be poorly-received.*
64+
- Submit a pull request. As a pull request the RFC will receive design feedback from the larger community, and the
65+
author should be prepared to revise it in response.
66+
- Update the pull request to add the number of the PR to the filename and add a link to the PR in the header of the RFC.
67+
- Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those
68+
that don't receive any comments.
69+
- Eventually, the DataHub team will decide whether the RFC is a candidate for inclusion.
70+
- RFCs that are candidates for inclusion will entire a "final comment period" lasting 7 days. The beginning of this
71+
period will be signaled with a comment and tag on the pull request. Furthermore, an announcement will be made in the
72+
\#rfc Slack channel for further visibility.
73+
- An RFC acan be modified based upon feedback from the DataHub team and community. Significant modifications may trigger
74+
a new final comment period.
75+
- An RFC may be rejected by the DataHub team after public discussion has settled and comments have been made summarizing
76+
the rationale for rejection. The RFC will enter a "final comment period to close" lasting 7 days. At the end of the "FCP
77+
to close" period, the PR will be closed.
78+
- An RFC author may withdraw their own RFC by closing it themselves. Please state the reason for the withdrawal.
79+
- An RFC may be accepted at the close of its final comment period. A DataHub team member will merge the RFC's associated
80+
pull request, at which point the RFC will become 'active'.
81+
82+
83+
## Details on Active RFCs
84+
85+
Once an RFC becomes active then authors may implement it and submit the feature as a pull request to the DataHub repo.
86+
Becoming 'active' is not a rubber stamp, and in particular still does not mean the feature will ultimately be merged; it
87+
does mean that the core team has agreed to it in principle and are amenable to merging it.
88+
89+
Furthermore, the fact that a given RFC has been accepted and is 'active' implies nothing about what priority is assigned
90+
to its implementation, nor whether anybody is currently working on it.
91+
92+
Modifications to active RFC's can be done in followup PR's. We strive to write each RFC in a manner that it will reflect
93+
the final design of the feature; but the nature of the process means that we cannot expect every merged RFC to actually
94+
reflect what the end result will be at the time of the next major release; therefore we try to keep each RFC document
95+
somewhat in sync with the language feature as planned, tracking such changes via followup pull requests to the document.
96+
97+
## Implementing an RFC
98+
99+
The author of an RFC is not obligated to implement it. Of course, the RFC author (like any other developer) is welcome
100+
to post an implementation for review after the RFC has been accepted.
101+
102+
An active RFC should have the link to the implementation PR(s) listed, if there are any. Feedback to the actual
103+
implementation should be conducted in the implementation PR instead of the original RFC PR.
104+
105+
If you are interested in working on the implementation for an 'active' RFC, but cannot determine if someone else is
106+
already working on it, feel free to ask (e.g. by leaving a comment on the associated issue).
107+
108+
## Implemented RFCs
109+
110+
Once an RFC has finally be implemented, first off, congratulations! And thank you for your contribution! Second, to
111+
help track the status of the RFC, please make one final PR to move the RFC from `docs/rfc/active` to
112+
`docs/rfc/finished`.
113+
114+
## Reviewing RFCs
115+
116+
Most of the DataHub team will attempt to review some set of open RFC pull requests on a regular basis. If a DataHub
117+
team member believes an RFC PR is ready to be accepted into active status, they can approve the PR using GitHub's
118+
review feature to signal their approval of the RFCs.
119+
120+
121+
122+
*DataHub's RFC process is inspired by many others, including [Vue.js](https://github.com/vuejs/rfcs) and
123+
[Ember](https://github.com/emberjs/rfcs).*

‎docs/rfc/templates/000-template.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
- Start Date: (fill me in with today's date, YYYY-MM-DD)
2+
- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name)
3+
- Discussion Issue: (GitHub issue this was discussed in before the RFC, if any)
4+
- Implementation PR(s): (leave this empty)
5+
6+
# <RFC title>
7+
8+
## Summary
9+
10+
> Brief explanation of the feature.
11+
12+
## Basic example
13+
14+
> If the proposal involves a new or changed API, include a basic code example. Omit this section if it's not applicable.
15+
16+
## Motivation
17+
18+
> Why are we doing this? What use cases does it support? What is the expected outcome?
19+
>
20+
> Please focus on explaining the motivation so that if this RFC is not accepted, the motivation could be used to develop
21+
> alternative solutions. In other words, enumerate the constraints you are trying to solve without coupling them too
22+
> closely to the solution you have in mind.
23+
24+
## Detailed design
25+
26+
> This is the bulk of the RFC.
27+
28+
> Explain the design in enough detail for somebody familiar with the framework to understand, and for somebody familiar
29+
> with the implementation to implement. This should get into specifics and corner-cases, and include examples of how the
30+
> feature is used. Any new terminology should be defined here.
31+
32+
## How we teach this
33+
34+
> What names and terminology work best for these concepts and why? How is this idea best presented? As a continuation
35+
> of existing DataHub patterns, or as a wholly new one?
36+
37+
> What audience or audiences would be impacted by this change? Just DataHub backend developers? Frontend developers?
38+
> Users of the DataHub application itself?
39+
40+
> Would the acceptance of this proposal mean the DataHub guides must be re-organized or altered? Does it change how
41+
> DataHub is taught to new users at any level?
42+
43+
> How should this feature be introduced and taught to existing audiences?
44+
45+
## Drawbacks
46+
47+
> Why should we *not* do this? Please consider the impact on teaching DataHub, on the integration of this feature with
48+
> other existing and planned features, on the impact of the API churn on existing apps, etc.
49+
50+
> There are tradeoffs to choosing any path, please attempt to identify them here.
51+
52+
## Alternatives
53+
54+
> What other designs have been considered? What is the impact of not doing this?
55+
56+
> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem.
57+
58+
## Rollout / Adoption Strategy
59+
60+
> If we implemented this proposal, how will existing users / developers adopt it? Is it a breaking change? Can we write
61+
> automatic refactoring / migration tools? Can we provide a runtime adapter library for the original API it replaces?
62+
63+
## Unresolved questions
64+
65+
> Optional, but suggested for first drafts. What parts of the design are still TBD?

‎docs/slack.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Slack
2+
3+
The DataHub team has an open source slack channel to discuss development and support.
4+
5+
[Sign up](https://join.slack.com/t/datahubspace/shared_invite/zt-dkzbxfck-dzNl96vBzB06pJpbRwP6RA) or [log in with an
6+
existing account](https://datahubspace.slack.com/) to `datahubspace` on Slack.

0 commit comments

Comments
 (0)