From dfec5b00dcec565d29faae519977dac6062ad0be Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Mon, 25 Oct 2021 14:35:35 -0700 Subject: [PATCH 01/12] initial proposal documentation proposal (draft) --- ...R01 - Proposal Documentation and Review.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 proposals/draft/Draft - PR01 - Proposal Documentation and Review.md diff --git a/proposals/draft/Draft - PR01 - Proposal Documentation and Review.md b/proposals/draft/Draft - PR01 - Proposal Documentation and Review.md new file mode 100644 index 0000000..53e4446 --- /dev/null +++ b/proposals/draft/Draft - PR01 - Proposal Documentation and Review.md @@ -0,0 +1,21 @@ +# Proposal Documentation and Review + +## Step 1: Open an Issue + +First, open an issue to confirm the idea is viable and has some interest from the community. + +## Step 2: Create the proposal doc + +When you are ready to draft the proposal, copy the template into a new page with the next available SIP number and begin to fill out the document. + +## Step 3: Discussion and Comment Period + +After the doc is created, start a new Discussion thread to request feedback. Cross link the discussion thread to your SIP proposal and vice versa. When your proposal is ready for review, change the status to "Ready for Review" and post a note to the original issue. + +## Step 4: Review Period + +The working group will pick 2-4 topics each month to review. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here in the form. + +## Step 5: Approval + +Approval conditions are still TBD, but generally SIPs will be approved if consensus is reasonably gathered from the majority of working group members - and if there are no "Strong No" votes from the working group leadership team. From 778e5d4f2269e64210f4c80136e7f88f2dc562fa Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Mon, 25 Oct 2021 14:37:15 -0700 Subject: [PATCH 02/12] rename with PR ID --- ... and Review.md => PR21 - Proposal Documentation and Review.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/draft/{Draft - PR01 - Proposal Documentation and Review.md => PR21 - Proposal Documentation and Review.md} (100%) diff --git a/proposals/draft/Draft - PR01 - Proposal Documentation and Review.md b/proposals/draft/PR21 - Proposal Documentation and Review.md similarity index 100% rename from proposals/draft/Draft - PR01 - Proposal Documentation and Review.md rename to proposals/draft/PR21 - Proposal Documentation and Review.md From f180b2d81110062df5e84282eb907e6b9815b13b Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Mon, 25 Oct 2021 14:55:50 -0700 Subject: [PATCH 03/12] incorporate template --- ...R21 - Proposal Documentation and Review.md | 108 ++++++++++++++++-- 1 file changed, 98 insertions(+), 10 deletions(-) diff --git a/proposals/draft/PR21 - Proposal Documentation and Review.md b/proposals/draft/PR21 - Proposal Documentation and Review.md index 53e4446..b25dd8b 100644 --- a/proposals/draft/PR21 - Proposal Documentation and Review.md +++ b/proposals/draft/PR21 - Proposal Documentation and Review.md @@ -1,21 +1,109 @@ -# Proposal Documentation and Review +# Proposal Documentation and Review Process -## Step 1: Open an Issue +## Status -First, open an issue to confirm the idea is viable and has some interest from the community. +| header | header | +| ------ | ------ | +| State | Draft \| Ready for Review \| Reviewing \| Accepted \| Not Accepted | +| Issue Link | (required link to issue) | +| Discussion Thread(s) | (optional link) | +| Created | 2021-09-27 | -## Step 2: Create the proposal doc +----------------------- -When you are ready to draft the proposal, copy the template into a new page with the next available SIP number and begin to fill out the document. +## Proposal -## Step 3: Discussion and Comment Period +### TL;DR Overview + +A proposal for drafting, submitting, reviewing, and approving proposals. + +### What specific change do you propose to make? + +We propose a process for submitting proposals, as described here in this proposal. + +------------------ + +#### Phase 1: Open an Issue + +First, open an issue to confirm the idea is viable and has some interest from the community. Ask others to comment on your issue and provide their feedback. + +#### Phase 2: Create the proposal doc + +When you are ready to draft the proposal, create a new branch starting with the issue number followed by a dash (`-`). Copy the [document template](../template.md) and fill out the proposal template. + +Commit to your branch, push, and then open a new PR that links back to your original issue. + +#### Phase 3: Discussion and Comment Period After the doc is created, start a new Discussion thread to request feedback. Cross link the discussion thread to your SIP proposal and vice versa. When your proposal is ready for review, change the status to "Ready for Review" and post a note to the original issue. -## Step 4: Review Period +#### Phase 4: Review Period + +The working group will pick 1-3 topics each month to review. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here in the form. + +#### Phase 5: Approval + +SIPs will be approved if consensus is gained from the majority of working group members - and if there are no "Strong No" votes from the working group leadership team. + +------------------ + +### Which layer(s) of the Singer ecosystem does this proposal directly touch? + +Select all that apply: + +- [ ] Singer Specification - required capabilities and behaviors +- [ ] Singer Specification - optional capabilities and behaviors +- [ ] Singer best practices and other guidance +- [x] Singer Working Group - practices and procedures +- [ ] Singer documentation (Other) + +## Motivation + +In order to deliberate on and select specific changes to the Singer protocol and established standards and best practices. + +### What problem does it solve? + +... + +### Why is it needed? + +... + +## Other Considerations +> > +### Are there any downsides to this change? + +... + +### Is the change backwards compatible? + +... + +### Which users are affected by the change? + +... + +### How are users affected by the change? (e.g. DB upgrade required?) + +... + +### Prototype Implementations + +...(if applicable)... + +### Future Plans + +...(if applicable)... + +### Excluded Alternatives + +...(if applicable)... + +### Acknowledgements + +...(if applicable)... -The working group will pick 2-4 topics each month to review. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here in the form. +## What defines this SIP as "done"? -## Step 5: Approval +... -Approval conditions are still TBD, but generally SIPs will be approved if consensus is reasonably gathered from the majority of working group members - and if there are no "Strong No" votes from the working group leadership team. From fde29bc3b7985ba44b0e5f6a85f6943cfe841a8b Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Mon, 25 Oct 2021 15:31:34 -0700 Subject: [PATCH 04/12] fill template --- ...R21 - Proposal Documentation and Review.md | 38 ++++++++++--------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/proposals/draft/PR21 - Proposal Documentation and Review.md b/proposals/draft/PR21 - Proposal Documentation and Review.md index b25dd8b..bf88908 100644 --- a/proposals/draft/PR21 - Proposal Documentation and Review.md +++ b/proposals/draft/PR21 - Proposal Documentation and Review.md @@ -41,10 +41,12 @@ After the doc is created, start a new Discussion thread to request feedback. Cro The working group will pick 1-3 topics each month to review. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here in the form. -#### Phase 5: Approval +#### Phase 5: Approval or Non-Approval SIPs will be approved if consensus is gained from the majority of working group members - and if there are no "Strong No" votes from the working group leadership team. +If the SIP is not approved, it will return to draft status and/or it may be replaced by a new or altered submission based on Working Group feedback. + ------------------ ### Which layer(s) of the Singer ecosystem does this proposal directly touch? @@ -63,47 +65,49 @@ In order to deliberate on and select specific changes to the Singer protocol and ### What problem does it solve? -... +The process provides a specific and actionable path to propose improvements to the Singer specification, documentation, and other community resources. ### Why is it needed? -... +Currently there is no established means for proposals to be incorporated back into the spec, and there is no specific process for those proposals to receive careful review and constructive feedback. ## Other Considerations -> > + +1. We may want to incorporate into the process a set of rules for what is in or out of scope for this working group. +2. We should plan for the process (or at least the proposal template) to evolve over time. + ### Are there any downsides to this change? -... +None. ### Is the change backwards compatible? -... +N/A - Not applicable. -### Which users are affected by the change? +### How are Singer developers affected by the change (if applicable)? -... +Developers may receive guidance and/or provide feedback by reading and engaging with SIP documents through the draft, review, and approval process. -### How are users affected by the change? (e.g. DB upgrade required?) +### How are Singer users affected by the change? (e.g. DB upgrade required?) -... +Users over time should see more robust capabilities and more uniform behaviors across taps and targets. -### Prototype Implementations +### Prototype Implementations (if available) -...(if applicable)... +Not applicable. ### Future Plans -...(if applicable)... +Over a period of submissions, we likely will evolve this format and process based on learnings. ### Excluded Alternatives -...(if applicable)... +Not applicable. ### Acknowledgements -...(if applicable)... +N/A ## What defines this SIP as "done"? -... - +The process will be approved for use by the Working Group. From c5b14b28afc37fbef398e459efa83e768aae1b7a Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Tue, 30 Nov 2021 06:18:18 -0800 Subject: [PATCH 05/12] update proposal and template text --- ...R21 - Proposal Documentation and Review.md | 82 ++++++++++--------- proposals/template.md | 57 ++++++++----- 2 files changed, 83 insertions(+), 56 deletions(-) diff --git a/proposals/draft/PR21 - Proposal Documentation and Review.md b/proposals/draft/PR21 - Proposal Documentation and Review.md index bf88908..652d713 100644 --- a/proposals/draft/PR21 - Proposal Documentation and Review.md +++ b/proposals/draft/PR21 - Proposal Documentation and Review.md @@ -1,17 +1,17 @@ # Proposal Documentation and Review Process -## Status +## Proposal Status | header | header | | ------ | ------ | -| State | Draft \| Ready for Review \| Reviewing \| Accepted \| Not Accepted | +| State | Ready for Review | | Issue Link | (required link to issue) | | Discussion Thread(s) | (optional link) | | Created | 2021-09-27 | ----------------------- -## Proposal +## I. Proposal Summary ### TL;DR Overview @@ -21,33 +21,53 @@ A proposal for drafting, submitting, reviewing, and approving proposals. We propose a process for submitting proposals, as described here in this proposal. ------------------- +### Motivation -#### Phase 1: Open an Issue +In order to deliberate on and select specific changes to the Singer protocol and established standards and best practices. + +### What problem does it solve? + +The process provides a specific and actionable path to propose improvements to the Singer specification, documentation, and other community resources. + +### Why is it needed? + +Currently there is no established means for proposals to be incorporated back into the spec, and there is no specific process for those proposals to receive careful review and constructive feedback. + +----------------------- + +## II. Proposal Details + +New improvement proposals will leverage the following process. + +### Phase 1: Open an Issue First, open an issue to confirm the idea is viable and has some interest from the community. Ask others to comment on your issue and provide their feedback. -#### Phase 2: Create the proposal doc +### Phase 2: Create the proposal doc When you are ready to draft the proposal, create a new branch starting with the issue number followed by a dash (`-`). Copy the [document template](../template.md) and fill out the proposal template. Commit to your branch, push, and then open a new PR that links back to your original issue. -#### Phase 3: Discussion and Comment Period +### Phase 3: Discussion and Comment Period After the doc is created, start a new Discussion thread to request feedback. Cross link the discussion thread to your SIP proposal and vice versa. When your proposal is ready for review, change the status to "Ready for Review" and post a note to the original issue. -#### Phase 4: Review Period +### Phase 4: Review Period The working group will pick 1-3 topics each month to review. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here in the form. -#### Phase 5: Approval or Non-Approval +### Phase 5: Approval or Non-Approval SIPs will be approved if consensus is gained from the majority of working group members - and if there are no "Strong No" votes from the working group leadership team. If the SIP is not approved, it will return to draft status and/or it may be replaced by a new or altered submission based on Working Group feedback. ------------------- +----------------------- + +## III. Additional Information + + ### Which layer(s) of the Singer ecosystem does this proposal directly touch? @@ -56,58 +76,46 @@ Select all that apply: - [ ] Singer Specification - required capabilities and behaviors - [ ] Singer Specification - optional capabilities and behaviors - [ ] Singer best practices and other guidance -- [x] Singer Working Group - practices and procedures +- [x] **Singer Working Group - practices and procedures** - [ ] Singer documentation (Other) -## Motivation - -In order to deliberate on and select specific changes to the Singer protocol and established standards and best practices. - -### What problem does it solve? +### Are there any downsides to this change? -The process provides a specific and actionable path to propose improvements to the Singer specification, documentation, and other community resources. +None. -### Why is it needed? + -## Other Considerations +### Other Considerations 1. We may want to incorporate into the process a set of rules for what is in or out of scope for this working group. 2. We should plan for the process (or at least the proposal template) to evolve over time. -### Are there any downsides to this change? - -None. - -### Is the change backwards compatible? - -N/A - Not applicable. - ### How are Singer developers affected by the change (if applicable)? Developers may receive guidance and/or provide feedback by reading and engaging with SIP documents through the draft, review, and approval process. -### How are Singer users affected by the change? (e.g. DB upgrade required?) +### How are Singer users affected by the change (if applicable)? Users over time should see more robust capabilities and more uniform behaviors across taps and targets. -### Prototype Implementations (if available) + ### Future Plans -Over a period of submissions, we likely will evolve this format and process based on learnings. +Over a period of submissions, we likely will continue to evolve this format and process based on learnings. -### Excluded Alternatives + -### Acknowledgements + -## What defines this SIP as "done"? +### What defines this SIP as "done"? The process will be approved for use by the Working Group. diff --git a/proposals/template.md b/proposals/template.md index 3f053f8..25216bb 100644 --- a/proposals/template.md +++ b/proposals/template.md @@ -1,25 +1,20 @@ -Process: +# SIP #`` - `` -1. It's recommended to first open an issue to confirm the idea is viable and has some interest from the community. -1. When you are ready to draft the proposal, copy the below into a new page with the next available SIP number and begin to fill out the document. -1. After the doc is created, start a new Discussion thread to request feedback. Cross link the discussion thread to your SIP proposal and vice versa. When your proposal is ready for review, change the status to "Ready for Review" and post a note to the original issue. -1. The working group will pick 2-4 topics each month to review. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here in the form. -1. Approval conditions are still TBD, but generally SIPs will be approved if consensus is reasonably gathered from the majority of working group members - and if there are no "Strong No" votes from the working group leadership team. +_This document follows the [Singer Improvement Proposal (SIP) process](./draft/PR21%20-%20Proposal%20Documentation%20and%20Review.md)_ ------------------------ - -## Status +## Proposal Status | header | header | | ------ | ------ | | State | Draft \| Ready for Review \| Reviewing \| Accepted \| Not Accepted | | Issue Link | (required link to issue) | | Discussion Thread(s) | (optional link) | -| Created | 2021-09-27 | +| Created | YYYY-MM-DD | +| Updated | YYYY-MM-DD | ----------------------- -## Proposal +## I. Proposal Summary ### TL;DR Overview @@ -30,7 +25,7 @@ Process: ...(Detailed description)... ## Motivation -> > + ... ### What problem does it solve? @@ -41,8 +36,28 @@ Process: ... -## Other Considerations -> > +----------------------- + +## II. Proposal Details + +...(Detailed information here)... + +----------------------- + +## III. Additional Information + + + +### Which layer(s) of the Singer ecosystem does this proposal directly touch? + +Select all that apply: + +- [ ] Singer Specification - required capabilities and behaviors +- [ ] Singer Specification - optional capabilities and behaviors +- [ ] Singer best practices and other guidance +- [x] **Singer Working Group - practices and procedures** +- [ ] Singer documentation (Other) + ### Are there any downsides to this change? ... @@ -51,11 +66,15 @@ Process: ... -### Which users are affected by the change? +### Other Considerations ... -### How are users affected by the change? (e.g. DB upgrade required?) +### How are Singer developers affected by the change (if applicable)? + +... + +### How are Singer users affected by the change? (if applicable)? ... @@ -71,10 +90,10 @@ Process: ...(if applicable)... -### Acknowledgements +### Acknowledgements ...(if applicable)... -## What defines this SIP as "done"? +### What defines this SIP as "done"? -... \ No newline at end of file +... From a660c631115efa4c92bbd2812cd262affafb26be Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Tue, 30 Nov 2021 06:50:53 -0800 Subject: [PATCH 06/12] add issue link --- ...R21 - Proposal Documentation and Review.md | 21 +++++++------------ 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/proposals/draft/PR21 - Proposal Documentation and Review.md b/proposals/draft/PR21 - Proposal Documentation and Review.md index 652d713..01addbb 100644 --- a/proposals/draft/PR21 - Proposal Documentation and Review.md +++ b/proposals/draft/PR21 - Proposal Documentation and Review.md @@ -2,12 +2,11 @@ ## Proposal Status -| header | header | +| Status | _Ready for Review_ | | ------ | ------ | -| State | Ready for Review | -| Issue Link | (required link to issue) | -| Discussion Thread(s) | (optional link) | +| Issue Link | [#12](https://github.com/MeltanoLabs/Singer-Working-Group/issues/12) | | Created | 2021-09-27 | +| Updated | 2021-11-30 | ----------------------- @@ -45,19 +44,15 @@ First, open an issue to confirm the idea is viable and has some interest from th ### Phase 2: Create the proposal doc -When you are ready to draft the proposal, create a new branch starting with the issue number followed by a dash (`-`). Copy the [document template](../template.md) and fill out the proposal template. +When you are ready to draft the proposal, create a new branch starting with the issue number followed by a dash (`-`). Copy the [document template](../template.md) and fill out the proposal template. Commit to your branch, push, and then open a new PR that links back to your original issue. -Commit to your branch, push, and then open a new PR that links back to your original issue. +When your proposal is ready for review, change the status to "Ready for Review" and post a note to the original issue. -### Phase 3: Discussion and Comment Period +### Phase 3: Review Period -After the doc is created, start a new Discussion thread to request feedback. Cross link the discussion thread to your SIP proposal and vice versa. When your proposal is ready for review, change the status to "Ready for Review" and post a note to the original issue. +The working group will pick 1-3 topics each month to review from those in "Ready for Review" status. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here into the proposal document. -### Phase 4: Review Period - -The working group will pick 1-3 topics each month to review. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here in the form. - -### Phase 5: Approval or Non-Approval +### Phase 4: Approval or Non-Approval SIPs will be approved if consensus is gained from the majority of working group members - and if there are no "Strong No" votes from the working group leadership team. From 1058cfcee2549901494ee234749edc3048b254f9 Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Tue, 30 Nov 2021 06:57:25 -0800 Subject: [PATCH 07/12] additional vote process details --- proposals/draft/PR21 - Proposal Documentation and Review.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/draft/PR21 - Proposal Documentation and Review.md b/proposals/draft/PR21 - Proposal Documentation and Review.md index 01addbb..5eec278 100644 --- a/proposals/draft/PR21 - Proposal Documentation and Review.md +++ b/proposals/draft/PR21 - Proposal Documentation and Review.md @@ -52,9 +52,11 @@ When your proposal is ready for review, change the status to "Ready for Review" The working group will pick 1-3 topics each month to review from those in "Ready for Review" status. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here into the proposal document. +Over the course of review, the working group members may add comments and suggestions to the pull request directly. The author may likewise update the proposal text to address any submitted feedback. Authors should update the "Date Updated" field in the doc whenever changes are applied. + ### Phase 4: Approval or Non-Approval -SIPs will be approved if consensus is gained from the majority of working group members - and if there are no "Strong No" votes from the working group leadership team. +SIPs will be approved if consensus is gained from the majority of working group members. Each member company may vote "Strong Yes", "Yes", "No", or "Strong No". To be approved, a proposal requires a simple majority of "Strong Yes" or "Yes" votes from member companies and no "Strong No" votes from the working group leadership team. If the SIP is not approved, it will return to draft status and/or it may be replaced by a new or altered submission based on Working Group feedback. From 51818eab8f5452b28508604df15fbee914b34c43 Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Tue, 22 Feb 2022 06:28:38 -0800 Subject: [PATCH 08/12] updated proposal, add group page --- group/index.md | 33 +++ ...R21 - Proposal Documentation and Review.md | 192 ++++++++++++++++++ proposals/approved/.gitkeep | 0 proposals/draft/.gitkeep | 0 ...R21 - Proposal Documentation and Review.md | 118 ----------- proposals/reviewing/.gitkeep | 0 6 files changed, 225 insertions(+), 118 deletions(-) create mode 100644 group/index.md create mode 100644 proposals/PR21 - Proposal Documentation and Review.md delete mode 100644 proposals/approved/.gitkeep delete mode 100644 proposals/draft/.gitkeep delete mode 100644 proposals/draft/PR21 - Proposal Documentation and Review.md delete mode 100644 proposals/reviewing/.gitkeep diff --git a/group/index.md b/group/index.md new file mode 100644 index 0000000..c1059a9 --- /dev/null +++ b/group/index.md @@ -0,0 +1,33 @@ +# Working Group Membership + +The Singer Working Group is comprised of several companies each invested in the success of the Singer Spec. + +## Member Companies + +In working group documents, members are referred to as "Member Companies", "Group Members", or simply "Members". + +Members do not pay dues and do not receive any payment for membership. To be considered for membership, a company must have some history of using Singer and contributing within the community, and they should have reference to their own use of Singer on their company's external website. + +## Group Leadership + +We aim to always have 3 companies in position of leadership, called "Leading Members" in our working group documents. + +The current Leading Members are: + +- [Meltano](https://www.meltano.com) - Maintainers of the [SDK for Taps and Targets](https://sdk.meltano.com/en/latest/) and [MeltanoHub for Singer](https://hub.meltano.com/singer/). +- [Talend](https://www.talend.com) - Maintainers of [Singer.io](https://Singer.io), the [Singer Spec docs](https://github.com/singer-io/getting-started/blob/master/docs/SPEC.md), and [StitchData.com](https://stitchdata.com). +- [Wise](https://wise.com/us/) - Maintainers of [PipelineWise](https://transferwise.github.io/pipelinewise/). + +### Responsibilities of Leadership + +Leading Members are expected to: + +1. Regularly attend and participate in working group sessions, +2. Participate in proposal review discussions, and +3. Register a vote on new proposals within the designated voting period of each proposal. + +## New Members + +In general, we are open to accepting any company into our group which is similarly committed to the success of the Singer spec and the Singer community. + +New membership invites may proposed by way of nomination internally. Any existing Member Company may nominate a company to be invited, subject to approval by majority vote from the Leading Members. diff --git a/proposals/PR21 - Proposal Documentation and Review.md b/proposals/PR21 - Proposal Documentation and Review.md new file mode 100644 index 0000000..a34a6f5 --- /dev/null +++ b/proposals/PR21 - Proposal Documentation and Review.md @@ -0,0 +1,192 @@ +# Proposal Documentation and Review Process + +## Proposal Status + +| Status | _Reviewing_ | +| ------ | ------ | +| Issue Link | [#12](https://github.com/MeltanoLabs/Singer-Working-Group/issues/12) | +| Created | 2021-09-27 | +| Updated | 2021-02-21 | + +----------------------- + +## I. Proposal Summary + +### TL;DR Overview + +A proposal for drafting, submitting, reviewing, voting on, and approving proposals. + +### What specific change do you propose to make? + +We propose a process for submitting and managing proposals, as described here in this proposal. + +### Motivation + +In order to deliberate on and select specific changes to the Singer protocol and established standards and best practices. + +### What problem does it solve? + +The process provides a specific and actionable path to propose improvements to the Singer specification, documentation, and other community resources. + +### Why is it needed? + +This proposal established means for proposals to be incorporated back into the spec, and there is no specific process for those proposals to receive careful review and constructive feedback. + +----------------------- + +## II. Proposal Details + +Each new "Singer Improvement Proposal" (or "SIP") shall leverage the following process. + +### Phase 1: Open an Issue + +First, open an issue in GitHub to confirm the idea is viable and has some interest from the community. Ask others to comment on your issue and provide their feedback. + +### Phase 2: Create the proposal doc + +When you are ready to draft the proposal, create a new branch starting with the issue number followed by a dash ('-'). The branch may be created in the primary repo if permissions allow, or a forked version of the repo otherwise. + +Given an original issue number `14` and PR number `21` in GitHub: + +- Example Proposal Title: "Add Widget to Singer" +- Example Branch Name: `14-add-widget-to-singer` or `forkid/14-add-widget-to-singer` +- Example File Name: `proposals/PR21 - Add Widget to Singer.md` + +Copy the [document template](../template.md) and fill out the proposal. Commit to your branch, push, and then open a new PR that links back to your original issue. + +When your proposal is ready for review, change the status to "Ready for Review" and post a note to the original issue. + +### Phase 3: Review Period + +The working group will pick 1-3 topics each month to review from those in "Ready for Review" status. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here into the proposal document. + +Over the course of review, the working group members may add comments and suggestions to the pull request directly. If changes to the text of the proposal are needed as a result of the review process, the author(s) shall update the relevant proposal text to address this feedback to continue moving forward in the review process. Author(s) shall also update the "Date Updated" field in the doc whenever changes are applied. + +### Phase 4: Voting Period + +At the end of the review period, and when all feedback has been addressed, a member of the leadership group will post to the pull request that "voting is open" on the proposal. + +#### Voting + +Once voting is open, one representative from each Members Company may post a vote: + +1. "Strong Yes" +2. "Yes" +3. "No" +4. "Strong No" + +All Member Companies are encouraged to vote, but only the Leading Members are _required_ to vote. + +#### Vote Scoring + +Votes from all Member Companies are scored, but only votes from Leading Members will typically impact whether or not the proposal passes. + +| Vote | Leading Members | Other Members | +|--|--|--| +| "Strong Yes" | `+1.0` | `+0.01` | +| "Yes" | `+1.0` | `+0.01` | +| "No" | `-1.0` | `-0.01` | +| "Strong No" | `-2.5` | `-0.01` | + +After summing the value of all qualified votes, and after the voting period has passed: + +- Scores `>=1.0`: `Approved` +- Scores `<1.0`: `Not Approved` + +Note that with 3 Leading Member Companies, a "Strong No" from a Leading Member is essentially a veto vote. If a Leading Member does not want to approve but also does not want to veto, then a simple "No" vote may be logged. In that scenario, the proposal will then be approved only if both other Leading Members vote "Yes". + +### Phase 5: Approval or Non-Approval + +If the SIP is approved, the author shall perform the following steps: + +1. Update the document status to "Approved". +2. Update the document file name to use the next available SIP number as three digit 0-padded integer. + - For example: if your proposal is titled `Process for XYZ` and the prior approved SIP number was `012`, then your new file name would be `013 - Process for XYZ.md`. +3. Add the new document title, with hyperlink, to the "Approved" section of the index (`proposals/index.md`). +4. Merge the pull request. + +If the SIP is not approved, it will return to draft status and/or it may be replaced by a new or altered submission based on Working Group feedback. + +### Document Lifecycle Edits + +Occasionally, existing Proposal documents may need to be edited or updated for readability or clarification. Modifications to approved proposals will be managed using the following process: + +1. Any Member Company may propose edits or clarifications by submitting a pull request against the document. +2. The author shall add a "Change log" section to the document, with an entry describing the nature of the update(s). +3. The author should request approval from one or more Leading Members. +4. The pull request may be merged by the author, pending at least one approval on the pull request from a Leading Member. + +This Edit process _should not_ be used for any significant changes which would significantly alter or undo prior decisions. Significant modifications and revisions shall require a fresh vote, and any Leading Member may reject the proposed edit and/or request the edit be submitted as a formal Proposal. + +Examples of valid lifecycle edits: + +1. Expanding upon documentation which may have otherwise been unclear. +2. Correcting small grammatical or spelling issues. +3. Creating or updating section headers for readability. +4. Improving readability by providing examples of a specific use case or behavior. +5. Adding hyperlinks and references to related resources. +6. Adding or updating a table of contents. +7. Minor updates to working group processes, especially if those updates don't impact general function or outcomes. (For example, extending a review period from 14 days to 21 days.) + +Examples of significant edits which should instead be submitted as formal proposals: + +1. Updating from one standard framework to a newer version of the same standard. +1. Introducing significant changes to key processes or to a critical function of the spec. +1. Any other substantive change that could impact the stability or interoperability of the spec. + +----------------------- + +## III. Additional Information + + + +### Which layer(s) of the Singer ecosystem does this proposal directly touch? + +Select all that apply: + +- [ ] Singer Specification - required capabilities and behaviors +- [ ] Singer Specification - optional capabilities and behaviors +- [ ] Singer best practices and other guidance +- [x] **Singer Working Group - practices and procedures** +- [ ] Singer documentation (Other) + +### Are there any downsides to this change? + +None. + + + +### Other Considerations + +1. We may want to incorporate into the process a set of rules for what is in or out of scope for this working group. +2. We should plan for the process (or at least the proposal template) to evolve over time. + +### How are Singer developers affected by the change (if applicable)? + +Developers may receive guidance and/or provide feedback by reading and engaging with SIP documents through the draft, review, and approval process. + +### How are Singer users affected by the change (if applicable)? + +Users over time should see more robust capabilities and more uniform behaviors across taps and targets. + + + +### Future Plans + +Over a period of submissions, we likely will continue to evolve this format and process based on learnings. + + + + + +### What defines this SIP as "done"? + +The process will be approved for use by the Working Group. diff --git a/proposals/approved/.gitkeep b/proposals/approved/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/proposals/draft/.gitkeep b/proposals/draft/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/proposals/draft/PR21 - Proposal Documentation and Review.md b/proposals/draft/PR21 - Proposal Documentation and Review.md deleted file mode 100644 index 5eec278..0000000 --- a/proposals/draft/PR21 - Proposal Documentation and Review.md +++ /dev/null @@ -1,118 +0,0 @@ -# Proposal Documentation and Review Process - -## Proposal Status - -| Status | _Ready for Review_ | -| ------ | ------ | -| Issue Link | [#12](https://github.com/MeltanoLabs/Singer-Working-Group/issues/12) | -| Created | 2021-09-27 | -| Updated | 2021-11-30 | - ------------------------ - -## I. Proposal Summary - -### TL;DR Overview - -A proposal for drafting, submitting, reviewing, and approving proposals. - -### What specific change do you propose to make? - -We propose a process for submitting proposals, as described here in this proposal. - -### Motivation - -In order to deliberate on and select specific changes to the Singer protocol and established standards and best practices. - -### What problem does it solve? - -The process provides a specific and actionable path to propose improvements to the Singer specification, documentation, and other community resources. - -### Why is it needed? - -Currently there is no established means for proposals to be incorporated back into the spec, and there is no specific process for those proposals to receive careful review and constructive feedback. - ------------------------ - -## II. Proposal Details - -New improvement proposals will leverage the following process. - -### Phase 1: Open an Issue - -First, open an issue to confirm the idea is viable and has some interest from the community. Ask others to comment on your issue and provide their feedback. - -### Phase 2: Create the proposal doc - -When you are ready to draft the proposal, create a new branch starting with the issue number followed by a dash (`-`). Copy the [document template](../template.md) and fill out the proposal template. Commit to your branch, push, and then open a new PR that links back to your original issue. - -When your proposal is ready for review, change the status to "Ready for Review" and post a note to the original issue. - -### Phase 3: Review Period - -The working group will pick 1-3 topics each month to review from those in "Ready for Review" status. Once selected for review, update the doc status to "Reviewing" and enter the comment-by-date deadline here into the proposal document. - -Over the course of review, the working group members may add comments and suggestions to the pull request directly. The author may likewise update the proposal text to address any submitted feedback. Authors should update the "Date Updated" field in the doc whenever changes are applied. - -### Phase 4: Approval or Non-Approval - -SIPs will be approved if consensus is gained from the majority of working group members. Each member company may vote "Strong Yes", "Yes", "No", or "Strong No". To be approved, a proposal requires a simple majority of "Strong Yes" or "Yes" votes from member companies and no "Strong No" votes from the working group leadership team. - -If the SIP is not approved, it will return to draft status and/or it may be replaced by a new or altered submission based on Working Group feedback. - ------------------------ - -## III. Additional Information - - - -### Which layer(s) of the Singer ecosystem does this proposal directly touch? - -Select all that apply: - -- [ ] Singer Specification - required capabilities and behaviors -- [ ] Singer Specification - optional capabilities and behaviors -- [ ] Singer best practices and other guidance -- [x] **Singer Working Group - practices and procedures** -- [ ] Singer documentation (Other) - -### Are there any downsides to this change? - -None. - - - -### Other Considerations - -1. We may want to incorporate into the process a set of rules for what is in or out of scope for this working group. -2. We should plan for the process (or at least the proposal template) to evolve over time. - -### How are Singer developers affected by the change (if applicable)? - -Developers may receive guidance and/or provide feedback by reading and engaging with SIP documents through the draft, review, and approval process. - -### How are Singer users affected by the change (if applicable)? - -Users over time should see more robust capabilities and more uniform behaviors across taps and targets. - - - -### Future Plans - -Over a period of submissions, we likely will continue to evolve this format and process based on learnings. - - - - - -### What defines this SIP as "done"? - -The process will be approved for use by the Working Group. diff --git a/proposals/reviewing/.gitkeep b/proposals/reviewing/.gitkeep deleted file mode 100644 index e69de29..0000000 From 344fa2f2c71f131de739abea0e7d59319c333a32 Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Tue, 22 Feb 2022 06:58:55 -0800 Subject: [PATCH 09/12] accept suggested fix Co-authored-by: Pat Nadolny --- group/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/group/index.md b/group/index.md index c1059a9..e7e4021 100644 --- a/group/index.md +++ b/group/index.md @@ -30,4 +30,4 @@ Leading Members are expected to: In general, we are open to accepting any company into our group which is similarly committed to the success of the Singer spec and the Singer community. -New membership invites may proposed by way of nomination internally. Any existing Member Company may nominate a company to be invited, subject to approval by majority vote from the Leading Members. +New membership invites may be proposed by way of nomination internally. Any existing Member Company may nominate a company to be invited, subject to approval by majority vote from the Leading Members. From a4cffd0817c008556fa8d5a70010d1b0ead1cf98 Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Tue, 22 Feb 2022 07:04:26 -0800 Subject: [PATCH 10/12] more direct "downsides" prompt --- proposals/PR21 - Proposal Documentation and Review.md | 2 +- proposals/template.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/PR21 - Proposal Documentation and Review.md b/proposals/PR21 - Proposal Documentation and Review.md index a34a6f5..563c88b 100644 --- a/proposals/PR21 - Proposal Documentation and Review.md +++ b/proposals/PR21 - Proposal Documentation and Review.md @@ -150,7 +150,7 @@ Select all that apply: - [x] **Singer Working Group - practices and procedures** - [ ] Singer documentation (Other) -### Are there any downsides to this change? +### What are the downsides to this change, if any? None. diff --git a/proposals/template.md b/proposals/template.md index 25216bb..1f93219 100644 --- a/proposals/template.md +++ b/proposals/template.md @@ -58,7 +58,7 @@ Select all that apply: - [x] **Singer Working Group - practices and procedures** - [ ] Singer documentation (Other) -### Are there any downsides to this change? +### What are the downsides to this change, if any? ... From 3ebfbe8971af5b1cddb132b452bec0f5c8f47231 Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Tue, 22 Feb 2022 07:16:05 -0800 Subject: [PATCH 11/12] add clause about Members as tie breakers --- proposals/PR21 - Proposal Documentation and Review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/PR21 - Proposal Documentation and Review.md b/proposals/PR21 - Proposal Documentation and Review.md index 563c88b..680c83b 100644 --- a/proposals/PR21 - Proposal Documentation and Review.md +++ b/proposals/PR21 - Proposal Documentation and Review.md @@ -93,7 +93,7 @@ After summing the value of all qualified votes, and after the voting period has - Scores `>=1.0`: `Approved` - Scores `<1.0`: `Not Approved` -Note that with 3 Leading Member Companies, a "Strong No" from a Leading Member is essentially a veto vote. If a Leading Member does not want to approve but also does not want to veto, then a simple "No" vote may be logged. In that scenario, the proposal will then be approved only if both other Leading Members vote "Yes". +Note that with 3 Leading Member Companies, a "Strong No" from a Leading Member is essentially a veto vote. If a Leading Member does not want to approve but also does not want to veto, then a simple "No" vote may be logged. In that scenario, the proposal will then be approved only if both other Leading Members vote "Yes" _and_ if "No" votes from other Members do not outweigh the Members' "Yes" votes. (The 'Other Members' votes are the tie breakers in this case.) ### Phase 5: Approval or Non-Approval From 8bcb399de895b226684c05d36cea73ef62c192ca Mon Sep 17 00:00:00 2001 From: "Aaron (\"AJ\") Steers" Date: Tue, 22 Feb 2022 07:17:01 -0800 Subject: [PATCH 12/12] fixed math --- proposals/PR21 - Proposal Documentation and Review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/PR21 - Proposal Documentation and Review.md b/proposals/PR21 - Proposal Documentation and Review.md index 680c83b..7732d3d 100644 --- a/proposals/PR21 - Proposal Documentation and Review.md +++ b/proposals/PR21 - Proposal Documentation and Review.md @@ -85,7 +85,7 @@ Votes from all Member Companies are scored, but only votes from Leading Members |--|--|--| | "Strong Yes" | `+1.0` | `+0.01` | | "Yes" | `+1.0` | `+0.01` | -| "No" | `-1.0` | `-0.01` | +| "No" | `-2.0` | `-0.01` | | "Strong No" | `-2.5` | `-0.01` | After summing the value of all qualified votes, and after the voting period has passed: