Skip to content

Commit 9cc8c8d

Browse files
authored
docs: Update documentation on Epics and Supervising Maintainers (#17505)
* docs: Update documentation on Epics and Sponsoring Maintainers * Improve wording about finding sponsoring maintainers * rename to supervising maintainer
1 parent 9348304 commit 9cc8c8d

File tree

1 file changed

+48
-23
lines changed

1 file changed

+48
-23
lines changed

docs/source/contributor-guide/roadmap.md

Lines changed: 48 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -25,24 +25,25 @@ align to that vision.
2525

2626
## Planning `EPIC`s
2727

28-
DataFusion uses [GitHub
29-
issues](https://github.com/apache/datafusion/issues) to track
30-
planned work. We collect related tickets using tracking issues labeled
31-
with `[EPIC]` which contain discussion and links to more detailed items.
28+
DataFusion uses [GitHub issues] to track planned work. We collect related
29+
tickets using tracking issues marked with the `EPIC` label, containing
30+
discussion and links to more detailed items:
3231

33-
Epics offer a high level roadmap of what the DataFusion
34-
community is thinking about. The epics are not meant to restrict
35-
possibilities, but rather help the community see where development is
36-
headed, align our work, and inspire additional contributions.
32+
[github issues]: https://github.com/apache/datafusion/issues
3733

38-
As this project is entirely driven by volunteers, we welcome
39-
contributions for items not currently covered by epics. However,
40-
before submitting a large PR, we strongly suggest and request you
41-
start a conversation using a github issue or the
42-
[dev@arrow.apache.org](mailto:dev@arrow.apache.org) mailing list to
43-
make review efficient and avoid surprises.
34+
- [The current list of `EPIC`s can be found here.](https://github.com/apache/datafusion/issues?q=is%3Aissue%20state%3Aopen%20label%3AEPIC)
4435

45-
[The current list of `EPIC`s can be found here](https://github.com/apache/datafusion/issues?q=is%3Aissue+is%3Aopen+epic).
36+
- [The current list of `PROPOSAL EPIC` (that are not yet underway) can be found here.](https://github.com/apache/datafusion/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22PROPOSAL%20EPIC%22)
37+
38+
Epics offer a high level roadmap of what the DataFusion community is thinking
39+
about. The epics are not meant to restrict possibilities, but rather help
40+
organize the community and make it easier to see where development is headed,
41+
align our work, and inspire additional contributions.
42+
43+
We also welcome contributions for items not covered by epics. However, before
44+
submitting a large PR, we strongly suggest and request you start a conversation as described in [Discussing New Features](#discussing-new-features) below.
45+
46+
[dev@arrow.apache.org]: mailto:dev@arrow.apache.org
4647

4748
## Quarterly Roadmap
4849

@@ -62,14 +63,38 @@ For more information:
6263
### Discussing New Features
6364

6465
If you plan to work on a new feature that doesn't have an existing ticket, it is
65-
a good idea to open a ticket to discuss the feature. Advanced discussion often
66-
helps avoid wasted effort by determining early if the feature is a good fit for
67-
DataFusion before too much time is invested. Discussion on a ticket can help
68-
gather feedback from the community and is likely easier to discuss than a 1000
69-
line PR.
70-
71-
If you open a ticket and it doesn't get any response, you can try `@`-mentioning
72-
recently active community members in the ticket to get their attention.
66+
a good idea to open one for discussion. Advanced discussion helps avoid wasted
67+
effort by determining if the feature is a good fit for DataFusion before too
68+
much time is invested. Discussion on a ticket can help gather feedback from the
69+
community and is likely easier to discuss than a 1000 line PR.
70+
71+
Maintainers will mark major proposals as `PROPOSED EPIC` to make them more
72+
visible, but we are very limited on review bandwidth. If you open a ticket and it
73+
doesn't get any response, try `@`-mentioning recently active community members
74+
in the ticket, or [posting to the mailing list or Discord](communication.md).
75+
76+
### Supervising Maintainers
77+
78+
We have found that most successful epics have one or more "supervising
79+
maintainers", a committer ([see here for current list]) who take the lead on
80+
reviewing and committing PRs, helps with design, and coordinates and
81+
communicates with the community. If you want to ship a large feature, we
82+
recommend finding such maintainer upfront; otherwise, your PRs may
83+
remain unreviewed for a very long time.
84+
85+
Supervising maintainers have no additional formal authority and there is
86+
currently no formal process for appointing, approving or tracking who has that
87+
role for a given epic. Instead, we rely on discussion on the ticket or PR.
88+
Helping complete an epic is a significant time commitment, so maintainers are
89+
more likely to help features they are particularly interested in or align with
90+
their own project's use of DataFusion.
91+
92+
If you are willing to be a supervising maintainer for a feature, please say so
93+
explicitly. If you are unsure, we suggest asking directly who is willing to take
94+
the role, as it can be hard to tell sometimes whether a committer is simply
95+
participating and giving general feedback.
96+
97+
[see here for current list]: governance.md
7398

7499
### What Contributions are Good Fits?
75100

0 commit comments

Comments
 (0)