Skip to content

feat(docs): migrate RFC process back to main repository #15242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

feat(docs): migrate RFC process back to main repository #15242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9eaf8f1
feat(docs): migrate RFC process back to main repository
shirshanka Nov 8, 2025
9b963bb
fix(docs): update RFC Slack channel to #contribute-code
shirshanka Nov 8, 2025
6978224
fix(docs): fix documentation build issues
shirshanka Nov 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added ...ev-access-acryldata-datahub-fork-feature--forms-analytics-gcs-integration-1be76c63.tar.gz
View file
Open in desktop
Binary file not shown.
1 change: 1 addition & 0 deletions docs-website/generateDocsDir.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ function list_markdown_files(): string[] {
/^docker\/(?!README|datahub-upgrade|airflow\/local_airflow)/, // Drop all but a few docker docs.
/^docs\/docker\/README\.md/, // This one is just a pointer to another file.
/^docs\/README\.md/, // This one is just a pointer to the hosted docs site.
/^docs\/rfcs\/template\.md/, // RFC template file should not be processed
/^\s*$/, //Empty string
];

Expand Down
142 changes: 75 additions & 67 deletions docs-website/sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -754,50 +754,51 @@ module.exports = {
type: "doc",
id: "docs/api/graphql/overview",
},
{
Reference: [
{
type: "doc",
label: "Queries",
id: "graphql/queries",
},
{
type: "doc",
label: "Mutations",
id: "graphql/mutations",
},
{
type: "doc",
label: "Objects",
id: "graphql/objects",
},
{
type: "doc",
label: "Inputs",
id: "graphql/inputObjects",
},
{
type: "doc",
label: "Interfaces",
id: "graphql/interfaces",
},
{
type: "doc",
label: "Unions",
id: "graphql/unions",
},
{
type: "doc",
label: "Enums",
id: "graphql/enums",
},
{
type: "doc",
label: "Scalars",
id: "graphql/scalars",
},
],
},
// TODO: Re-enable GraphQL Reference docs when generated
// {
// Reference: [
// {
// type: "doc",
// label: "Queries",
// id: "graphql/queries",
// },
// {
// type: "doc",
// label: "Mutations",
// id: "graphql/mutations",
// },
// {
// type: "doc",
// label: "Objects",
// id: "graphql/objects",
// },
// {
// type: "doc",
// label: "Inputs",
// id: "graphql/inputObjects",
// },
// {
// type: "doc",
// label: "Interfaces",
// id: "graphql/interfaces",
// },
// {
// type: "doc",
// label: "Unions",
// id: "graphql/unions",
// },
// {
// type: "doc",
// label: "Enums",
// id: "graphql/enums",
// },
// {
// type: "doc",
// label: "Scalars",
// id: "graphql/scalars",
// },
// ],
// },
{
Guides: [
{
Expand Down Expand Up @@ -880,29 +881,30 @@ module.exports = {
label: "Python SDK",
items: [
"metadata-ingestion/as-a-library",
{
type: "category",
label: "SDK Reference",
items: [
{
type: "category",
label: "Builder",
items: [{ type: "autogenerated", dirName: "python-sdk/builder" }],
},
{
type: "category",
label: "Clients",
items: [{ type: "autogenerated", dirName: "python-sdk/clients" }],
},
{
type: "category",
label: "SDK V2",
items: [{ type: "autogenerated", dirName: "python-sdk/sdk-v2" }],
},
"python-sdk/models",
"python-sdk/urns",
],
},
// TODO: Re-enable SDK Reference when docs are available
// {
// type: "category",
// label: "SDK Reference",
// items: [
// {
// type: "category",
// label: "Builder",
// items: [{ type: "autogenerated", dirName: "python-sdk/builder" }],
// },
// {
// type: "category",
// label: "Clients",
// items: [{ type: "autogenerated", dirName: "python-sdk/clients" }],
// },
// {
// type: "category",
// label: "SDK V2",
// items: [{ type: "autogenerated", dirName: "python-sdk/sdk-v2" }],
// },
// "python-sdk/models",
// "python-sdk/urns",
// ],
// },
],
},
{
Expand Down Expand Up @@ -1171,6 +1173,12 @@ module.exports = {
"docs/CONTRIBUTING",
"docs/links",
"docs/rfc",
{
type: "category",
label: "RFCs",
link: { type: "doc", id: "docs/rfcs/README" },
items: [],
},
"SECURITY",
],
},
Expand Down
26 changes: 13 additions & 13 deletions docs/rfc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,14 @@ consensus among the DataHub core teams.
An RFC goes through the following stages:

- _Discussion_ (Optional): Create an issue with the "RFC" label to have a more open ended, initial discussion around
your proposal (useful if you don't have a concrete proposal yet). Consider posting to #rfc in [Slack](./slack.md)
your proposal (useful if you don't have a concrete proposal yet). Consider posting to #contribute-code in [Slack](./slack.md)
for more visibility.
- _Pending_: when the RFC is submitted as a PR. Please add the "RFC" label to the PR.
- _Active_: when an RFC PR is merged and undergoing implementation.
- _Landed_: when an RFC's proposed changes are shipped in an actual release.
- _Rejected_: when an RFC PR is closed without being merged.

[Pending RFC List](https://github.com/datahub-project/rfcs/pulls?q=is%3Apr+is%3Aopen)
[Pending RFC List](https://github.com/datahub-project/datahub/pulls?q=is%3Apr+is%3Aopen+label%3ARFC)

## When to follow this process

Expand All @@ -48,29 +48,29 @@ with a polite request to submit an RFC first.

It's often helpful to get feedback on your concept before diving into the level of API design detail required for an
RFC. You may open an issue on this repo to start a high-level discussion, with the goal of eventually formulating an RFC
pull request with the specific implementation design. We also highly recommend sharing drafts of RFCs in #rfc on the
pull request with the specific implementation design. We also highly recommend sharing drafts of RFCs in #contribute-code on the
[DataHub Slack](./slack.md) for early feedback.

## The process

In short, to get a major feature added to DataHub, one must first get the RFC merged into the RFC repo as a markdown
In short, to get a major feature added to DataHub, one must first get the RFC merged into the main DataHub repository as a markdown
file. At that point the RFC is 'active' and may be implemented with the goal of eventual inclusion into DataHub.

- Fork the [datahub-project/rfc repository](https://github.com/datahub-project/rfcs).
- Copy the `000-template.md` template file to `rfc/active/000-my-feature.md`, where `my-feature` is more
- Fork the [datahub-project/datahub repository](https://github.com/datahub-project/datahub).
- Copy the `template.md` file from `docs/rfcs/` to `docs/rfcs/active/000-my-feature.md`, where `my-feature` is more
descriptive. Don't assign an RFC number yet.
- Fill in the RFC. Put care into the details. _RFCs that do not present convincing motivation, demonstrate understanding
of the impact of the design, or are disingenuous about the drawback or alternatives tend to be poorly-received._
- Submit a pull request. As a pull request the RFC will receive design feedback from the larger community, and the
- Submit a pull request with the "RFC" label. As a pull request the RFC will receive design feedback from the larger community, and the
author should be prepared to revise it in response.
- 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.
- Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those
that don't receive any comments.
- Eventually, the DataHub team will decide whether the RFC is a candidate for inclusion.
- RFCs that are candidates for inclusion will entire a "final comment period" lasting 7 days. The beginning of this
- RFCs that are candidates for inclusion will enter a "final comment period" lasting 7 days. The beginning of this
period will be signaled with a comment and tag on the pull request. Furthermore, an announcement will be made in the
\#rfc Slack channel for further visibility.
- An RFC acan be modified based upon feedback from the DataHub team and community. Significant modifications may trigger
\#contribute-code Slack channel for further visibility.
- An RFC can be modified based upon feedback from the DataHub team and community. Significant modifications may trigger
a new final comment period.
- An RFC may be rejected by the DataHub team after public discussion has settled and comments have been made summarizing
the rationale for rejection. The RFC will enter a "final comment period to close" lasting 7 days. At the end of the "FCP
Expand Down Expand Up @@ -106,9 +106,9 @@ already working on it, feel free to ask (e.g. by leaving a comment on the associ

## Implemented RFCs

Once an RFC has finally be implemented, first off, congratulations! And thank you for your contribution! Second, to
help track the status of the RFC, please make one final PR to move the RFC from `rfc/active` to
`rfc/finished`.
Once an RFC has finally been implemented, first off, congratulations! And thank you for your contribution! Second, to
help track the status of the RFC, please make one final PR to move the RFC from `docs/rfcs/active` to
`docs/rfcs/accepted`.

## Reviewing RFCs

Expand Down
42 changes: 42 additions & 0 deletions docs/rfcs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# DataHub RFCs

This directory contains Request for Comments (RFC) documents for substantial changes to DataHub.

## What is an RFC?

RFCs are design documents that propose significant changes to DataHub. See [the RFC process documentation](../rfc.md) for full details on when and how to submit an RFC.

## Fresh Start (2025)

**Note:** RFCs have moved back to the main DataHub repository (from the separate `datahub-project/rfcs` repo) to improve visibility and reduce contributor friction.

This represents a fresh start for the RFC process. Historical RFCs from before 2025 remain accessible in:

- Git history (commit `dbb4c84cb2` and earlier)
- Archived external repository: https://github.com/datahub-project/rfcs

Historical RFCs will be migrated to this directory on an as-needed basis when they become relevant for discussion or implementation.

## Directory Structure

- **[active/](./active/)** - RFCs currently under discussion or implementation
- **[accepted/](./accepted/)** - RFCs that have been implemented and shipped
- **[template.md](./template.md)** - Template for creating new RFCs

## Active RFCs

Currently, there are no active RFCs. Check the [pull requests with the "RFC" label](https://github.com/datahub-project/datahub/pulls?q=is%3Apr+is%3Aopen+label%3ARFC) for pending RFC proposals.

## Accepted RFCs

No RFCs have been accepted in this new structure yet.

## Contributing an RFC

1. Read the [RFC process documentation](../rfc.md)
2. Copy `template.md` to `active/000-my-feature.md`
3. Fill in the template with your proposal
4. Submit a pull request with the "RFC" label
5. Gather feedback and iterate on the design

For questions or early feedback, post in the #contribute-code channel on [DataHub Slack](../slack.md).
93 changes: 93 additions & 0 deletions docs/rfcs/template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
- Start Date: (fill me in with today's date, YYYY-MM-DD)
- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name)
- Discussion Issue: (GitHub issue this was discussed in before the RFC, if any)
- Implementation PR(s): (leave this empty)

# \<RFC title\>

## Summary

> Brief explanation of the feature.

## Basic example

> If the proposal involves a new or changed API, include a basic code example. Omit this section if it's not applicable.

## Motivation

> Why are we doing this? What use cases does it support? What is the expected outcome?
>
> Please focus on explaining the motivation so that if this RFC is not accepted, the motivation could be used to develop
> alternative solutions. In other words, enumerate the constraints you are trying to solve without coupling them too
> closely to the solution you have in mind.

## Requirements

> What specific requirements does your design need to meet? This should ideally be a bulleted list of items you wish
> to achieve with your design. This can help everyone involved (including yourself!) make sure your design is robust
> enough to meet these requirements.
>
> Once everyone has agreed upon the set of requirements for your design, we can use this list to review the detailed
> design.

### Extensibility

> Please also call out extensibility requirements. Is this proposal meant to be extended in the future? Are you adding
> a new API or set of models that others can build on in later? Please list these concerns here as well.

## Non-Requirements

> Call out things you don't want to discuss in detail during this review here, to help focus the conversation. This can
> include things you may build in the future based off this design, but don't wish to discuss in detail, in which case
> it may also be wise to explicitly list that extensibility in your design is a requirement.
>
> This list can be high level and not detailed. It is to help focus the conversation on what you want to focus on.

## Detailed design

> This is the bulk of the RFC.

> Explain the design in enough detail for somebody familiar with the framework to understand, and for somebody familiar
> with the implementation to implement. This should get into specifics and corner-cases, and include examples of how the
> feature is used. Any new terminology should be defined here.

## How we teach this

> What names and terminology work best for these concepts and why? How is this idea best presented? As a continuation
> of existing DataHub patterns, or as a wholly new one?

> What audience or audiences would be impacted by this change? Just DataHub backend developers? Frontend developers?
> Users of the DataHub application itself?

> Would the acceptance of this proposal mean the DataHub guides must be re-organized or altered? Does it change how
> DataHub is taught to new users at any level?

> How should this feature be introduced and taught to existing audiences?

## Drawbacks

> Why should we _not_ do this? Please consider the impact on teaching DataHub, on the integration of this feature with
> other existing and planned features, on the impact of the API churn on existing apps, etc.

> There are tradeoffs to choosing any path, please attempt to identify them here.

## Alternatives

> What other designs have been considered? What is the impact of not doing this?

> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem.

## Rollout / Adoption Strategy

> If we implemented this proposal, how will existing users / developers adopt it? Is it a breaking change? Can we write
> automatic refactoring / migration tools? Can we provide a runtime adapter library for the original API it replaces?

## Future Work

> Describe any future projects, at a very high level, that will build off this proposal. This does not need to be
> exhaustive, nor does it need to be anything you work on. It just helps reviewers see how this can be used in the
> future, so they can help ensure your design is flexible enough.

## Unresolved questions

> Optional, but suggested for first drafts. What parts of the design are still TBD?
Loading