[flang] Reference LLVM RFC process in Flang docs, with caveats#190836
[flang] Reference LLVM RFC process in Flang docs, with caveats#190836AlexisPerry wants to merge 4 commits intollvm:mainfrom
Conversation
AlexisPerry
changed the title
| [LLVM contribution process](https://llvm.org/docs/Contributing.html). | ||
|
|
||
| In the case of proposing substantive changes to either the Flang codebase or community practices, please follow the LLVM [Request for Comment (RFC) process](https://llvm.org/docs/RFCProcess.html) with the following caveats: | ||
| - Currently, there is no Flang Area Team to facilitate decision making. The present best practice is for the RFC author to periodically summarize the discussion to date, clearly state the apparent next steps, and list any outstanding questions needing resolution. If a rough consensus has been reached, please indicate this in the summary comment. |
There was a problem hiding this comment.
Maybe we should discuss this as a community, but my assumption was always that in the absence of an area team, maintainers make decisions in their area and the lead maintainers have the final say in anything contested. If others agree, perhaps we should link to Maintainers.md here.
As a maintainer I am happy to be pinged on any relevant RFCs that I have missed.
There was a problem hiding this comment.
I agree. I think this should be made clear. Adding a link to Maintainers.md is a good idea.
tarunprabhu
left a comment
tarunprabhu
left a comment
There was a problem hiding this comment.
Thanks for putting this together. Some thoughts.
| [LLVM contribution process](https://llvm.org/docs/Contributing.html). | ||
|
|
||
| In the case of proposing substantive changes to either the Flang codebase or community practices, please follow the LLVM [Request for Comment (RFC) process](https://llvm.org/docs/RFCProcess.html) with the following caveats: | ||
| - Currently, there is no Flang Area Team to facilitate decision making. The present best practice is for the RFC author to periodically summarize the discussion to date, clearly state the apparent next steps, and list any outstanding questions needing resolution. If a rough consensus has been reached, please indicate this in the summary comment. |
There was a problem hiding this comment.
I agree. I think this should be made clear. Adding a link to Maintainers.md is a good idea.
| [LLVM contribution process](https://llvm.org/docs/Contributing.html). | ||
|
|
||
| In the case of proposing substantive changes to either the Flang codebase or community practices, please follow the LLVM [Request for Comment (RFC) process](https://llvm.org/docs/RFCProcess.html) with the following caveats: | ||
| - Currently, there is no Flang Area Team to facilitate decision making. The present best practice is for the RFC author to periodically summarize the discussion to date, clearly state the apparent next steps, and list any outstanding questions needing resolution. If a rough consensus has been reached, please indicate this in the summary comment. |
There was a problem hiding this comment.
Do we want to require a periodic summary, or is a single summary at the end of the discussion sufficient? If the former, we should probably provide some guidance on how frequent this should be.
There was a problem hiding this comment.
I put in the part about periodic summaries mostly because I have found it helpful when the discussion has gone on for a bit and there have been a lot of contributions (admittedly, fuzzy numbers there). It's also a good way to get an RFC un-stuck, particularly the part about listing apparent next steps as it gives the commenters something concrete to agree with or object to.
There was a problem hiding this comment.
Fair points. It would be good to provide some guidance on how periodic such summaries should be - but I don't have a sense for what would be reasonable. It's probably ok to just leave this text as is and rely on the poster's best judgment.
| Contributions to Flang are done using GitHub Pull Requests and follow the | ||
| [LLVM contribution process](https://llvm.org/docs/Contributing.html). | ||
|
|
||
| In the case of proposing substantive changes to either the Flang codebase or community practices, please follow the LLVM [Request for Comment (RFC) process](https://llvm.org/docs/RFCProcess.html) with the following caveats: |
There was a problem hiding this comment.
Should we encourage posting on Discourse/Slack in case a contributor is not clear if the change is large enough to require an RFC?
There was a problem hiding this comment.
The LLVM RFC document I link to says "The proposal should be posted to the appropriate forum on Discourse.", so they will at least know where to post an RFC. As far as determining if an RFC is warranted, I'm not sure we need to expressly say where to ask that question here. Further down in this document, there are sections that describe the use of Discourse and Slack. Worst case, they put up an RFC that isn't that big a change and it's a quick yes or no.
There was a problem hiding this comment.
We want to make things as easy, and as clear, for new (or even infrequent) contributors as possible. Since all open-source projects work differently, getting familiar with a community, their preferred communication channels, and processes can be challenging even for experienced OSS contributors. IMO, this is addressing a question that potential contributors are likely to have.
|
|
||
| In the case of proposing substantive changes to either the Flang codebase or community practices, please follow the LLVM [Request for Comment (RFC) process](https://llvm.org/docs/RFCProcess.html) with the following caveats: | ||
| - Currently, there is no Flang Area Team to facilitate decision making. The present best practice is for the RFC author to periodically summarize the discussion to date, clearly state the apparent next steps, and list any outstanding questions needing resolution. If a rough consensus has been reached, please indicate this in the summary comment. | ||
| - Ideally, if the RFC is discussed on a community call, reference the meeting notes directly in the summary comment, whether to indicate that a decision was reached or simply to point to the relevant discussion. |
There was a problem hiding this comment.
Should we make this stronger and require summarizing the discussion that took place on a call? I have seen RFC's that look like they have not been resolved when in fact the discussion on a call did address any outstanding questions.
There was a problem hiding this comment.
I think that's a good idea. Would removing "Ideally" be sufficient?
There was a problem hiding this comment.
I would be tempted to ask for a more "customized" summary than simply referencing the meeting notes. The meeting notes don't usually capture all the details of the discussions. But these details are often very relevant in a detailed discussion. We have contributors who cannot attend the calls, so this would be very useful for them.
|
|
||
| In the case of proposing substantive changes to either the Flang codebase or community practices, please follow the LLVM [Request for Comment (RFC) process](https://llvm.org/docs/RFCProcess.html) with the following caveats: | ||
| - Currently, there is no Flang Area Team to facilitate decision making. The present best practice is for the RFC author to periodically summarize the discussion to date, clearly state the apparent next steps, and list any outstanding questions needing resolution. If a rough consensus has been reached, please indicate this in the summary comment. | ||
| - Ideally, if the RFC is discussed on a community call, reference the meeting notes directly in the summary comment, whether to indicate that a decision was reached or simply to point to the relevant discussion. |
There was a problem hiding this comment.
The use of "community" here seems a little ambiguous to me. We did have a dedicated "community" call once. Could we provide examples of such calls? Something like this, for instance:
| - Ideally, if the RFC is discussed on a community call, reference the meeting notes directly in the summary comment, whether to indicate that a decision was reached or simply to point to the relevant discussion. | |
| - Ideally, if the RFC is discussed on a community call - such as the Combined call, or the OpenMP call, reference the meeting notes directly in the summary comment, whether to indicate that a decision was reached or simply to point to the relevant discussion. |
There was a problem hiding this comment.
What if it's an RFC that affects both Flang and Clang, and it ends up being discussed on a Clang call, maybe even resolved there? Is the OpenMP call the only call outside the strict Flang community that is acceptable for resolving Flang-related RFCs? By leaving it a little vague, we don't preclude linking to any of the calls' minutes in the summary comment.
Personally, I think of the "Combined call" as the "Flang Community call", and perhaps we should start referring to it as such. When we just call it "Combined" it begs the question of what was combined? In this case, we know it was the Flang Technical Call and the Flang Community Call, but effectively it is the call where the Flang community gets together to discuss things live, and so I see it more like the latter subsumed the former. What do you think?
There was a problem hiding this comment.
I'm fine with just referring to the "combined" call as the "community" call going forward and replacing any references to "combined" with something else.
The point here was to make it clear what we are referring to when we say "community call". This document is intended for (relative) newcomers, who probably don't have as much context, so providing examples just makes it easier. We could include links to the non-flang calls in the examples as well.
Co-authored-by: Tarun Prabhu <tarunprabhu@gmail.com>
Co-authored-by: Tarun Prabhu <tarunprabhu@gmail.com>
5 participants
This PR is pursuant to a discussion held on the March 25th Flang Community Call regarding how to document our community's RFC best practices for the benefit of new contributors and facilitating a smoother decision making process overall.