Skip to content

Latest commit

 

History

History
109 lines (87 loc) · 7.33 KB

CONTRIBUTING.md

File metadata and controls

109 lines (87 loc) · 7.33 KB
Raw

This document highlights the procedures to contribute to the Digital Standard.

Overview:

  • 1: Digital Standard Schedule Overview
  • 2: Release Management committee
  • 3: How anyone can make suggested changes
  • 4: How we will approve (or deny, archive, save for later) suggested changes

1: Digital Standard Schedule Overview

We will do quarterly releases the first Tuesday of the following months: December (Q4) March (Q1) June (Q2) September (Q3)

The first quarterly release under this process and format is October 6, 2020, (the only release that is not done on the first Tuesday of the month as we are starting this process now). The other upcoming dates for the coming year will be:

  • December 1, 2020
  • March 2, 2021
  • June 1, 2021
  • September 7, 2021

We will compile recommended changes in GitHub on a branch with structure. For example:

  • Year_Month_x.y.z
  • 2020_09_1.2.0
  • 2020_12_1.3.0
  • 2021_03_1.4.0

Versioning — we will use point versioning system that follows x.y.z versioning, indicating:

  • x - major release (e.g. significant changes beyond the usual release changes)
  • y - minor release (e.g. minor changes, regular quarterly releases)
  • z - bug fix (e.g. small text edit that can happen between quarterly releases if determined by the CR Release Management Committee)

There are 5 key events that will happen every quarter leading up to the release.

  1. Step 1: Open comment period: Between quarterly release dates
  2. Step 2: 4 weeks before release: Public governance meeting to discuss priority changes
  3. Step 3: 2 weeks before release: CR release management meeting to finalize decisions (approve, archive, for later)
  4. Step 4: 1-3 days before release: Merge changes into the current DS version branch
  5. Step 5: Day of release: Share out to the public the new version of the Digital Standard.

2. Consumer Reports’ Digital Standard Release Management Committee

There are currently 5 Consumer Reports affiliated team members who will have privileges to have final review and approve the changes. Those people are: @cody-f @billfitzg @benrito @stephtngu-CR @mrerecich

3: How anyone can contribute to the Digital Standard:

There are 3 ways people can make suggested changes, modifications, or propose ideas:

  • 3a: Make a change through a GitHub pull request: These are tangible, specific, more modular text related changes.
  • 3b: Suggest a GitHub issue: These are potentially ideas or concepts that you would like to include or suggest to change against the Digital Standard for consideration. This may require additional research.
  • 3c: Email us for ideas to collaborate: This is where you would like to discuss a specific way to engage with us.

3a. Make a text change through a GitHub pull request

  • Between quarterly releases, anyone can add or suggest changes to the current Github branch (for the first one, the branch will be 2020_09_1.2.0) In order to suggest a change to the actual text or structure of the digital standard, follow these steps.
  • Go to the Digital Standard repository [https://github.com/TheDigitalStandard/TheDigitalStandard/tree/master]
  • Switch branches to the current version (e.g. 2020_09_1.2.0)
  • Based on what you want your change to be, go to the appropriate folder that contains the text you would like to change.
  • Click the pencil icon (edit this file)
  • Make the desired text change in the body of that file.
  • Scroll down and select: “Create a new branch for this commit and start a pull request”
  • In the title box, please use 7-10 words (roughly one very concise sentence) that explains the modification.
  • In the description box, if needed, please say more (~1-5 sentences) about why you are suggesting the change. Please use any context that would help us understand at a minimum: (1) reason for change (2) urgency
  • Please make sure you are making suggested pull requests to the proper branch.

3b. Suggest a GitHub issue.

  • Go to the Digital Standard repository [https://github.com/TheDigitalStandard/TheDigitalStandard/tree/master]
  • Click “Issues”
  • On the right hand side, click “New Issue”
  • In the title box, please use 7-10 words (roughly one very concise sentence) that explains the issue with helpful key words.
  • In the description box, if needed, please say more (~1-5 sentences) about why you are suggesting the change. Please use any context that would help us understand at a minimum: (1) reason for issue (2) urgency

3c. Email us for ideas to collaborate.

  • If you would like to reach out for any reason, including but not limited to the following: ⋅⋅* Work on building out a new area of the Digital Standard ⋅⋅* Collaborate on product or service testing in some capacity ⋅⋅* Conduct actual product or service testing using the Digital Standard
  • Please email us at: [[email protected]]

4. How we will approve (or deny, archive, save for later) suggested changes:

Step 1: Submit a pull request or issue to the GH repository. Be sure to include a short title and description indicating your topic.

Step 2: Digital Standard Public Governance Meeting: 2 weeks before the quarterly release date: We will hold a “Digital Standard Public Governance Meeting” which is open to the public (people who are interested in giving feedback or collaborating on version releases in some capacity).

  • This meeting will be 60 minutes and be conducted digitally via video conferencing.
  • Interested contributors will submit which issues they would like to discuss (ones that need discussion outside of the GitHub interface).
  • We will prioritize issues/pull requests that require discussion with the group. In order to do this, we will send out an editable Google Doc that people can contribute agenda items to discussing in advance. We will only allow discussion up to 60 minutes, so topics will need to be time bound appropriately. If there are smaller grammar or text edits, those will be deprioritized.
  • Each issue will be time-bound so we can get through the list of changes.
  • Note: We will rely on the Consumer Reports’ approval team to make the final decision on all issues and comments. The rationale behind decisions will be publicly available in the issue queue.

Step 3: CR Approval Committee Meeting: 1 week before the quarterly release date: The CR Approval Committee will review and approve the changes.

Team members can suggest to label the comments with one of the following:

  • Approve: Approve issue/PR change into the next version release.
  • Archive: Archive the issue/PR — the team will provide a reason for doing so.
  • For later: Delay the issue/PR to the next meeting or a designated time — the team will provide a reason for doing so.
  • In order for a change to be accepted, a minimum of 2 of the CR approval team will need to write “approve / archive / for later” to label the change.
  • Note: We will rely on the Consumer Reports’ approval team to make the final decision on all issues and comments.

Step 4: Merge approved changes into the upcoming branch release:

  • The day before release, the designated Digital Standard lead will merge the “Approved” issues/PR requests into the current branch release.

Step 5: Share out to the public the new version of the Digital Standard:

The day of release, the designated Digital Standard lead will share the new version of the Digital Standard. The new version should be available for download on [thedigitalstandard.org].