How to submit an open source contribution for Product Review

Overview

The goal is to define how contributions (new features or changes to existing functionality) will move through the product review process.

• All new product ideas - whether or not you intend to build them - must follow this product review process.

• Any code contribution that comes in as a pull request, without having submitted a product proposal, will not be reviewed until a product proposal is submitted.

  • Everyone should stop (code reviewing/developing) the PR

  • The team authoring the pull request must make a proposal and go through the product review process.

  • We would like to avoid wasting time - both on the code reviewer’s side as well as the code developer’s side - to be looking at something that doesn't have product review

Previously, contributions went through product review after PRs had been submitted and development work was already complete. We are inverting the process, so that product review and approval happens earlier, before the PRs are submitted. That way, when the PRs are submitted, the community and all relevant stakeholders have already come to agreement on the specs and expected behavior of the contribution.

Does my contribution require Product Review?

If the answer is “yes” to any of the following questions, then your contribution requires Product Review.

• Does this change or impact a feature that a learner would interact with?

• Does this change or impact part of the authoring flow?

• Does this change or impact the experience of configuring content or a course run?

• Does the change or impact reporting?

• Is this change related to Studio or Content Libraries?

• Is this change related to the LMS?

• Does this change impact the initial installation or the upgrade of the instance?

• Does this change impact a course’s OLX?

Note: Even if a feature is being built behind a feature flag, it must go through the Product Review process. If said feature is never intended to be part of the Core Product, then it’s better built as a plugin.

Roles

Access to GitHub for Product/Project Managers & WG Members

Product Review Process

1. Anyone/everyone in the community can create a proposal with user stories and a proposed solution

   1. Templates: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3890249759

   2. Create a Product Proposal ticket in the platform-roadmap GitHub repository

      1. You may need to first make a free account, https://github.com/signup

      2. Create your Product Proposal ticket here

   3. The ticket will get auto-added to the Open edX Roadmap project board:

2. The Submitter pings the Core Product Working Group in Slack (#wg-product-core) and shares the proposal

3. At each bi-monthly meeting, the Core Product Working Group will triage incoming proposals as follows:

   1. Assign 1 Coordinator per proposal. The Coordinator works with the Submitter to shepherd the proposal through the review process.

      1. Criteria:

         1. The Coordinator can be any member of the community, but it is helpful if the Coordinator has some connection to the Product Core WG or knows who might be a stakeholder in the project.

         2. The Coordinator can come from any organization, including the one that submitted the proposal.

         3. The Coordinator should do an initial review of the proposal, making sure all needed information is in the spec and it is clear and easy to read.

         4. The Coordinator for a given product proposal will be in charge of keeping status and labels of the corresponding roadmap ticket up-to-date. General OSPR management activities don’t include managing the product review process via the platform roadmap board.

      2. The group, coordinator, and/or proposer should add the appropriate label(s) to the GitHub ticket:

         1. What labels do we add to product proposals?

   2. The Coordinator and/or the Core PWG finds volunteers from any of the Product Working Group sub-groups to review the spec to offer general feedback on scope and approach.

      1. Criteria:

         1. Anyone with expertise in the product area can review, even folks from the same organization that submitted, but must have at least one reviewer from a different organization.

         2. See detailed information about finding reviewers here:

4. Reviewing The Spec

   1. The Coordinator should determine appropriate time boxes for review, and communicate that clearly to all reviewers

   2. Reviewers and/or coordinator should tap others to pull into the process based on the nature of the proposal (other product folks, end users, UX/UI experts, engineering leads)

   3. The Coordinator shares the proposal via the Forums to get broader community input. Please use the Collaborative Proposals section of the forums.

5. Finalizing the spec

   1. Feedback is incorporated by the Submitter

   2. Document release plans/roll-out plans, for proposals with a committed development team

6. Final approval comes from the Core Product Working Group and the proposal reviewers

   1. A proposal is considered approved if there are no outstanding objections

   2. If there are objections, then discussions continue until consensus (3/4 majority) is reached

   3. If consensus is not reached after the Core Product WG’s discussions:

      1. The Axim Product Team will make a final decision;

      2. If there is still discussion and disagreement, the TOC will be the final decider

   4. The Core Product Working Group determines if the proposal is part of the Core Product Offering or lies outside of it

      1. [needs further documentation/reference points - how is it determined? What evidence is needed? What consensus is required?]

7. Steps after product review is complete:

   1. Engineering/architecture review, if applicable (consult the Core Product WG if you need assistance determining if this is needed)

   2. Refinements or additional user stories

   3. Usability testing/AC testing

   4. Maintenance plan

8. Submitting Code

   1. All pull requests should clearly link to the Product Proposal GitHub Ticket. This will have the benefit of linking the pull request back to the Product Proposal ticket.

9. Refinements and Implementation Changes

   1. Any changes made during the implementation and delivery phases that veer away from the original designs or specs must be discussed with the original reviewers and approver(s) of the proposal. Discussion should take place in the original wiki proposal, including a description of the changes, justification and screenshots of any new designs.

Definitions:

Product Proposal

A Product Proposal is a document that describes a proposed change to the way some part of the Open edX platform currently works. A product proposal may come from an organization with a software engineering team proposing to actually implement the change; it may also come from a group or individual who wishes for the change to happen but cannot commit any software engineering resources to making the change happen. Either type of proposal is welcome. Please take care and time when making product proposals so that community members can understand What your change is and Why it is necessary. Please use the Product Proposal templates, , when making your proposal.

GitHub ticket

A GitHub ticket (also called a GitHub Issue) is very similar to a Jira ticket, Trello card, or other types of single-problem representation in an issue tracker system. We use GitHub because it is public and free - you do not need an account to browse GitHub tickets or boards (a GitHub board is the same as a Jira or Trello board, that is, a view into a collection of tickets).

• If you are unfamiliar with GitHub, this tutorial about GitHub Issues may be of help to you.

Finding Volunteers To Review Specs

• Volunteers should be anyone qualified to review the feature under discussion - these could be folks wearing product hats, super-user hats, instructional designer hats, etc.

• Anyone with expertise in the product area can review, even folks from the same organization that submitted, but must have at least one reviewer from a different organization.

• There is no “correct” number of volunteers, but features with substantial impact will generally warrant more than small ones.

• Volunteers should be recruited from specific sub-groups when it makes sense to, and if it is unclear who should review, ping the Product Core subgroup in the #wg-product-core Slack channel or attend a Product Core meeting.

• Note about UX/UI involvement: Part of the criteria for submitting a proposal is to include any early-stage concept frames that may exist, so it is valuable to get UX/UI input early. However, we should be mindful about protecting UX/UI time, especially for features where it is not clear the spec will get approved. Product reviewers should pull in UX/UI perspective only on the proposals that have a solid chance of passing the review, and/or when they might have questions.

  • UX/UI folx: this doesn’t mean you can’t provide a preliminary review unprompted, but please wait on providing a detailed design review until there is an emerging consensus that the feature will be approved in some form or another.

• If a proposal is stuck, a reviewer cannot be found, or the proposer/coordinator just can’t seem to find help, get in touch with the team at Axim as a last resort by tagging @axim-product-team in the #wg-product-core Slack channel.

• Engineering review isn’t necessary at this stage for most proposals. However, large/sweeping changes, fundamental rewrites of existing assumptions, and proposals that discuss adding new infrastructure pieces should find a senior engineer to weigh in. The Core Product WG and/or the Axim team can help determine if this type of review is needed.