-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: introducing the RFC process (#7)
* feat: introducing the RFC process This adds a first go at an RFC process for Open Job Description. The goal is to have a process defined with the expectation that we will iterate on it as we learn from it. Signed-off-by: Daniel Neilson <53624638+ddneilson@users.noreply.github.com>
- Loading branch information
Showing
8 changed files
with
309 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| blank_issues_enabled: false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| name: "Other Issues" | ||
| about: "Anything else regarding this repository" | ||
| title: issue title | ||
| --- | ||
|
|
||
| ## Description | ||
|
|
||
| A description of the issue, and a proposed resolution. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| name: "Request for Comment (RFC)" | ||
| description: "Create a tracking issue for an RFC." | ||
| title: "RFC: (short description)" | ||
| labels: | ||
| - rfc/proposed | ||
| assignees: | ||
| - ddneilson | ||
| - mwiebe | ||
| --- | ||
|
|
||
| * **Pull Request**: (Add the URL to the pull request here.) | ||
| * **Discussion Thread(s)**: | ||
| * (If there are discussion forum threads where this RFC has been discussed, then | ||
| please add URLs to those here. You can remove this bullet point otherwise.) | ||
|
|
||
| ## Description | ||
|
|
||
| A short description of the proposal. | ||
|
|
||
| ## Roles | ||
|
|
||
| | Role | User | ||
| | ---- | ---- | ||
| | Proposed By | @alias | ||
| | Author(s) | @alias | ||
|
|
||
| ## Workflow | ||
|
|
||
| - [x] Tracking issue created (label: `rfc/proposed`) | ||
| - [ ] RFC pull request submitted and ready for discussion (label: `rfc/exploring`) | ||
| - [ ] Last call for comments (labels: `rfc/exploring` and `rfc/final-comments`) | ||
| - [ ] Accepted and merged RFC pull request (label: `rfc/accepted-future`) | ||
| - [ ] Green-light for inclusion in a draft specification, and the author is creating and iterating on pull requests (label: `rfc/accepted-draft`) | ||
| - [ ] Pull requests are merged in to a draft specification (label: `rfc/accepted-staged`) | ||
| - [ ] Officially published in a non-draft revision of the specification (label: `rfc/released`) | ||
|
|
||
| Please close this tracking issue when the proposal enters the `Released` stage of the process. | ||
|
|
||
| ## Open Points | ||
|
|
||
| For easier discovery, especially if there is a lot of discussion on this issue, then please keep this section updated | ||
| with brief summaries and pointers to the main points of discussion. | ||
|
|
||
| --- | ||
|
|
||
| > The author is responsible to progress the RFC according to this checklist, and | ||
| apply the relevant labels to this issue. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| --- | ||
| name: "Wiki Documentation" | ||
| description: "Suggest a change or improvement to the wiki contents." | ||
| title: "Wiki: (short description)" | ||
| labels: | ||
| - wiki | ||
| --- | ||
|
|
||
| ## Description | ||
|
|
||
| *Describe the issue/recommendation.* | ||
|
|
||
| ## Links | ||
|
|
||
| *Link to affected documentation pages.* |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
|
|
||
| *Please choose the format that best matches the purpose of this pull request. Delete the top-level header of the chosen | ||
| section as well as all other sections.* | ||
|
|
||
| ## PR for RFC | ||
|
|
||
| ( Please use the form "feat(rfc): description" for the PR title. ) | ||
|
|
||
| **Tracking Issue**: {url} | ||
|
|
||
| This is a request for comments about {RFC description}. | ||
|
|
||
| ## PR for other purpose | ||
|
|
||
| ( Please use the form "feat: description", "fix: description", or "chore: description" for the | ||
| pull request title, as appropriate. ) | ||
|
|
||
| *Description of the change. What is being added or fixed?* | ||
|
|
||
| --- | ||
|
|
||
| By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
|
|
||
| * Feature Name: (fill in with a unique one or two word identifier. e.g. my_feature) | ||
| * RFC Tracking Issue: (fill in with the URL for the tracking issue in this repository) | ||
| * Start Date: (fill in with today's date: YYYY-MM-DD) | ||
| * Accepted On: (fill in with the date that the proposal was accepted: YYYY-MM-DD) | ||
|
|
||
| ## Summary | ||
|
|
||
| A one paragraph summary of the proposed feature. | ||
|
|
||
| ## Basic Examples | ||
|
|
||
| If the proposal involves a new or changed schema or syntax, then include some basic examples | ||
| that demonstrate how an end-user would use it. | ||
|
|
||
| ## Motivation | ||
|
|
||
| Why are we doing this? What use cases does it support? Focus on what sorts of workflows your | ||
| feature would enable for users. How common are those use cases: Are they specific to one | ||
| company's way of working, or more generally adopted? | ||
|
|
||
| If this is inspired by the capabilities of existing systems, then think about *why* the feature | ||
| is available in terms of what users accomplish with it. Our vision for Open Job Description is a | ||
| general and expressive specification rather than one that is a simply superset of features/syntax | ||
| available in existing distributed batch computing systems and pipeline tools. | ||
|
|
||
| ## Specification | ||
|
|
||
| What are the specific changes that are being proposed? | ||
|
|
||
| Please write this in a form similar to the official formal specification documents as though | ||
| it could just be dropped in to the existing documentation as-is. | ||
|
|
||
| ## Prior Art | ||
|
|
||
| Discuss prior art, both the good and the bad, in relation to the proposal. Does a feature | ||
| like this exist in other systems? How is it expressed in those system(s)? | ||
|
|
||
| ## Rejected Ideas | ||
|
|
||
| Why certain ideas that were brought while discussing this RFC were not ultimately pursued. | ||
|
|
||
| ## Copyright | ||
|
|
||
| This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,167 @@ | ||
| # Open Job Description RFCs | ||
|
|
||
| This directory is the place to propose and track upcoming changes to the Open Job Description standard. | ||
| The RFC ("Request For Comment") process is how Open Job Description achieves consensus on proposed | ||
| changes to the formal specification. The process is intended to provide a consistent and controlled | ||
| path for changes to the specification. | ||
|
|
||
| RFCs can be created by anyone in the community. If you have an idea, a kernel of an idea, or a | ||
| problem to solve then we encourage you to engage in this process. | ||
|
|
||
| **Jump to**: [RFC Process](#rfc-process) | [RFC Process Stages](#rfc-process-stages) | ||
|
|
||
| ## RFC Process | ||
|
|
||
| This section describes each state of the RFC process. | ||
|
|
||
| ### 1. Look for similar existing proposals or discussions | ||
|
|
||
| Before you start along the path of proposing your idea as an RFC, please take some time | ||
| to search through our [issues tracker] and [discussion forum] for similar or compatible | ||
| proposals. It is possible that your idea has previously been proposed, or it might fit | ||
| in nicely as an enhancement to an RFC that is in the works. | ||
|
|
||
| [issues tracker]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/issues | ||
| [discussion forum]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/discussions/categories/ideas | ||
|
|
||
| ### 2. Post in GitHub Discussions | ||
|
|
||
| As an informal starting point, we suggest that you try our discussion forums to have | ||
| some preliminary discussions on your proposal. These discussions can help find like-minded members of | ||
| the community to collaborate with, and test the idea with the community before commiting | ||
| to filling out an RFC template with the details of your proposal. | ||
|
|
||
| Simply create a new discussion thread in the [Ideas category] of the discussion forum to | ||
| get started. | ||
|
|
||
| [Ideas category]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/discussions/categories/ideas | ||
|
|
||
| ### 3. Tracking Issue | ||
|
|
||
| Each RFC has a GitHub issue which tracks it from start to finish. The issue is | ||
| the hub for conversations, community signal (+1s) and the issue number is used | ||
| as the unique identifier of this RFC. | ||
|
|
||
| Before creating a tracking issue, please search for similar or related ideas | ||
| in the issue list and discussion forum of this repo. If there is a relevant | ||
| RFC, collaborate on that existing RFC, based on its current stage. | ||
|
|
||
| Our [tracking issue template] includes a checklist of all the steps an RFC goes | ||
| through and it's the driver's responsibility to update the checklist and assign | ||
| the correct label to on the RFC throughout the process. | ||
|
|
||
| [tracking issue template]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/blob/master/.github/ISSUE_TEMPLATE/rfc.yml | ||
|
|
||
| ### 4. RFC Document | ||
|
|
||
| The next step is to write the first revision of the RFC document itself. | ||
|
|
||
| 1. First, [fork this repository] | ||
| 2. Then, in your fork: | ||
| 1. Create a file under `rfcs/NNNN-name.md` based off of the [0000-template.md] file. | ||
| `NNNN` in the filename is your tracking issue number, and `name` should be a one | ||
| or two word summary of the proposal. | ||
| 2. Please follow the template; it includes useful guidance and tips on how to write a good RFC. | ||
|
|
||
| [fork this repository]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo | ||
| [0000-template.md]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/blob/mainline/rfcs/0000-template.md | ||
|
|
||
| ### 5. Feedback | ||
|
|
||
| Once you have an initial version of your RFC document (it is completely fine to | ||
| submit an unfinished RFC to get initial feedback), [submit it as a pull request] | ||
| against this repository to start collecting feedback. | ||
|
|
||
| This is the likely going to be the longest part of your RFC process, and where | ||
| most of the feedback is collected. | ||
|
|
||
| A few tips: | ||
|
|
||
| - If you decide to resolve a comment without addressing it, take the time to | ||
| explain. | ||
| - Try to understand where people are coming from. If a comment seems off, ask | ||
| folks to elaborate and describe their use case or provide concrete examples. | ||
| - Work with the team member assigned to your tracking issue: if there are disagreements, | ||
| @mention them in a comment and ask them to provide their opinion. | ||
| - Be patient: it sometimes takes time for an RFC to converge. Some ideas need to "bake" | ||
| and solutions oftentimes emerge via a healthy debate. | ||
| - Not everything must be resolved in the first revision. It is okay to leave | ||
| some things to resolve later. Make sure to capture them clearly and have an | ||
| agreement about that. An RFC document may be updated/modified as new information | ||
| comes to light at any time before it it published in a revision of Open Job Description. | ||
|
|
||
| [submit it as a pull request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork | ||
|
|
||
| ### 6. Final Comments Period | ||
|
|
||
| At some point, you've reached consensus about most issues that were brought up | ||
| during the review period, and you are ready to merge. To allow "last call" on | ||
| feedback, the author can announce that the RFC enters "final comments period", | ||
| which means that within about a week or two, if no major concerns are raised, the | ||
| RFC will be approved and merged. | ||
|
|
||
| Add a comment on the RFC pull request, tracking issue, and discussion forum thread | ||
| if relevant that the RFC has entered this stage so that all relevant stakeholders | ||
| will be notified. | ||
|
|
||
| Once the final comments period is over, seek an approval of one of the core team | ||
| members, and you can merge your PR to the main branch. This will move your RFC | ||
| to the "Accepted-Future" state. | ||
|
|
||
| ### 7. Accepted and Beyond | ||
|
|
||
| The pull request for your RFC will be merged in to this repository when your proposal | ||
| has been accepted. This requires an approval of the pull request by one of the core | ||
| members of the Open Job Description team. | ||
|
|
||
| After merging the pull request, it may take some time for the core team to identify | ||
| which draft of the specification to include the proposal in; it may not be the current/next | ||
| one. | ||
|
|
||
| The team will contact you through your RFCs tracking issue when it is time to include | ||
| the proposal in the current draft specification. When that happens, we ask that you | ||
| prepare pull requests that modify the draft specification, user documentation, and | ||
| so on to include your proposed changes. | ||
|
|
||
| ## RFC Process Stages | ||
|
|
||
| An RFC's tracking ticket is tagged to indicate what stage of the process it is in: | ||
|
|
||
| | Stage | Tracking Label | Description | | ||
| | ----- | -------------- | ----------- | | ||
| | [0 - Proposed](#Proposed) | [rfc/proposed] | A proposal for a change that is offered for community and team evaluation. | | ||
| | [1 - Exploring](#Exploring) | [rfc/exploring] | The author(s), team, and community are working together to refine and iterate on the proposal. | | ||
| | [2 - Final Comments](#LastCall) | [rfc/exploring] and [rfc/final-comments] | Consensus has been reached on the RFC. A "last call" has been announced for feedback. | | ||
| | [3 - Accepted-Future](#Future) | [rfc/accepted-future] | The proposal has been accepted for inclusion in a future revision of the Open Job Description specification. | | ||
| | [4 - Accepted-Draft](#Draft) | [rfc/accepted-draft] | The author has been given the green light to include the proposal in a draft of the Open Job Description specification. | | ||
| | [5 - Accepted-Staged](#Staged) | [rfc/accepted-staged] | The proposal has been accepted and included in a draft revision of the Open Job Description specification. | | ||
| | [6 - Released](#Released) | [rfc/released] | The proposal has been included in a published revision of the Open Job Description specification. | | ||
|
|
||
| There are two additional statuses for RFCs that will not move forward: | ||
| - **[Abandoned](#Abandoned)** (label: [rfc/abandoned]) - The RFC's author(s) have ceased to engage in the process, and the RFC's process is | ||
| stalled. RFCs leave this state when the author(s) reengage, or a new champion from the community or team takes on | ||
| advocating for the proposal. | ||
| - **[Closed](#Closed)** - The RFC was closed by the author, or the review process determined that the proposal will | ||
| not be accepted. The tracking issue and pull request are closed in this stage. | ||
|
|
||
| [rfc/proposed]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/labels/rfc%2Fproposed | ||
| [rfc/exploring]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/labels/rfc%2Fexploring | ||
| [rfc/final-comments]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/labels/rfc%2Ffinal-comments | ||
| [rfc/accepted-future]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/labels/rfc%2Faccepted-future | ||
| [rfc/accepted-draft]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/labels/rfc%2Faccepted-draft | ||
| [rfc/accepted-staged]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/labels/rfc%2Faccepted-staged | ||
| [rfc/released]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/labels/rfc%2Freleased | ||
| [rfc/abandoned]: https://github.com/xxyggoqtpcmcofkc/openjd-specifications/labels/rfc%2Fabandoned | ||
|
|
||
| --- | ||
|
|
||
| This RFC process is inspired by RFC processes in popular open source projects: [Yarn RFC process], | ||
| [Rust RFC process], [React RFC process], [Ember RFC process], [AWS CDK RFC process], and [Python PEP]. | ||
|
|
||
| [yarn rfc process]: https://github.com/yarnpkg/rfcs | ||
| [rust rfc process]: https://github.com/rust-lang/rfcs | ||
| [react rfc process]: https://github.com/reactjs/rfcs | ||
| [ember rfc process]: https://github.com/emberjs/rfcs | ||
| [AWS CDK RFC process]: https://github.com/aws/aws-cdk-rfcs | ||
| [Python PEP]: https://peps.python.org/pep-0012/ | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters