/
How to submit an open source contribution for Product Review

How to submit an open source contribution for Product Review

Owned by Jenna Makowski
Last updated: Jan 06, 2025 by Cassie Zamparini
8 min read

 

Introduction

The objective of this document is to define the product review process for advancing new features or changes to current functionality. All new product ideas must follow the product review procedure and align with the latest release to be considered. Pull requests submitted without a prior product proposal will not be reviewed, and individuals should pause reviewing or developing such PRs. The responsible team must create a proposal and adhere to the review process to save time for both reviewers and developers by ensuring only approved items move forward.

Does my contribution require Product Review?

If you answer “yes” to any of the following questions, a Product Review is required. Features developed behind a feature flag must still follow the Product Review Process. If not intended for the Core Product, consider developing it as a plugin.

  1. Does this change or impact a feature that learners interact with?

  2. Does this change or impact the authoring flow?

  3. Does this change or impact the experience of configuring content or managing a course run?

  4. Does this change or impact reporting?

  5. Will this change affect user-facing features in any of these ways: altering appearance, modifying behavior, removing functionality, or introducing new functionality in:

    1. LMS (including legacy LMS code and non-Studio MFEs)

    2. Studio (including Studio MFE)

    3. Content Libraries

    4. If unsure, gather more information or contact the Product Working Group.

  6. Will this change affect the initial installation or upgrade process?

  7. Will this change impact a course’s OLX?

Examples that DO require Product Review:

  1. Enhanced Course Card Design in Open edX Dashboard: changes learner-facing features in the Core Product.

  2. Make it easy to configure LTIs and reuse settings: changes both author and learner-facing features in the Core Product.

  3. Libraries Relaunch - Component Reuse and Improved UI: changes author-facing and content management features in the Core Product.

Examples that DO NOT require Product Review:

  1. Broken Skip Link in Learner Dashboard: This is a bug fix that restores existing behavior without altering it.

  2. Add Plugin Slots for Progress Page Components: Backend-only change that does not affect user-facing features.

Examples that DO require Product Review:

  1. Enhanced Course Card Design in Open edX Dashboard: changes learner-facing features in the Core Product.

  2. Make it easy to configure LTIs and reuse settings: changes both author and learner-facing features in the Core Product.

  3. Libraries Relaunch - Component Reuse and Improved UI: changes author-facing and content management features in the Core Product.

Examples that DO NOT require Product Review:

  1. Broken Skip Link in Learner Dashboard: This is a bug fix that restores existing behavior without altering it.

  2. Add Plugin Slots for Progress Page Components: Backend-only change that does not affect user-facing features.

Product Review Process

Anyone within the community can create a Product Proposal. To submit a Product Proposal, follow the steps outlined below:

Step 1. Product Submitter Creates Proposal

  1. Choose your template:

    1. Contribution solves a problem and includes a solution, or

    2. Contribution identifies a problem, but requires discovery

  2. Ensure your proposal is added to the Proposed section on the wiki

  3. Add early-stage concept wireframes to your proposal only if it has a strong likelihood of approval. This ensures UX/UI resources are utilized effectively

Skip adding a Proposal if the suggested change is minor, or if it reintroduces a missing legacy feature. Please still provide enough detail outlining the change (eg. mockups, screencasts etc).

  1. Click here to create a Product Proposal issue on GitHub. Issues are auto-added to the Open edX Roadmap.

  2. Once you’ve created a GitHub issue, link to it at the top of your wiki Product Proposal, e.g:

    Screenshot 2024-08-06 at 11.24.48.png

Sign up here if you don’t have a GitHub account

  • Share your proposal on the Core Product Working Group Slack channel (#wg-product-core)

Example Slack message:
”Hi everyone, I’ve submitted a new product proposal [Product proposal name]:

  • Link to Proposal

  • Link to Github issue

I’d love your input.”

Ensure your Product Proposal is assigned to a Product Coordinator. The Product Coordinator oversees the product proposal's clarity and completeness, manages the GitHub issue, and product reviews. The Product Coordinator can be:

  1. a member of the community

  2. from any organization, including the one that submitted the proposal

It’s helpful if the Coordinator has a connection to the Product Core Working Group, or knows the stakeholder of the project. The submitter is also welcome to take on the role!

Step 1. Product Submitter Creates Proposal

  1. Choose your template:

    1. Contribution solves a problem and includes a solution, or

    2. Contribution identifies a problem, but requires discovery

  2. Ensure your proposal is added to the Proposed section on the wiki

  3. Add early-stage concept wireframes to your proposal only if it has a strong likelihood of approval. This ensures UX/UI resources are utilized effectively

Skip adding a Proposal if the suggested change is minor, or if it reintroduces a missing legacy feature. Please still provide enough detail outlining the change (eg. mockups, screencasts etc).

  1. Click here to create a Product Proposal issue on GitHub. Issues are auto-added to the Open edX Roadmap.

  2. Once you’ve created a GitHub issue, link to it at the top of your wiki Product Proposal, e.g:

    Screenshot 2024-08-06 at 11.24.48.png

Sign up here if you don’t have a GitHub account

  • Share your proposal on the Core Product Working Group Slack channel (#wg-product-core)

Example Slack message:
”Hi everyone, I’ve submitted a new product proposal [Product proposal name]:

  • Link to Proposal

  • Link to Github issue

I’d love your input.”

Ensure your Product Proposal is assigned to a Product Coordinator. The Product Coordinator oversees the product proposal's clarity and completeness, manages the GitHub issue, and product reviews. The Product Coordinator can be:

  1. a member of the community

  2. from any organization, including the one that submitted the proposal

It’s helpful if the Coordinator has a connection to the Product Core Working Group, or knows the stakeholder of the project. The submitter is also welcome to take on the role!

Step 2. Product Coordinator Coordinates Reviews

  1. Review the GitHub issue and Product Proposal and make sure everything is clear and easy to understand

  2. Update and manage statuses on the GitHub issue as needed (e.g. apply the status directly or move it to the corresponding GitHub project column):

    1. [Prod Proposals] New: A newly submitted proposal that requires evaluation by the community.

    2. [Prod Proposals] On Hold: A proposal requiring additional information before it can proceed to the review stage.

    3. [Prod Proposals] Ready for Review: The GitHub issue and proposal contain all necessary details for the review process to begin.

    4. [Resourced] Backlog: The proposal has passed review, is funded, and has assigned design and development teams, but is awaiting implementation.

    5. [Not Resourced] Backlog: The proposal has passed review but lacks funding and/or assigned design or development teams, and is awaiting implementation.

    6. In Design: The design phase is in progress, including creating mockups, wireframes, and/or prototypes, with feedback being gathered.

    7. Being Developed: Development work has begun, based on completed designs.

    8. Shipped: The implementation is complete, and the product is delivered.

  3. Apply and change labels on the GitHub issue when/if necessary:

    1. Needs more product information: Issue and proposal need more detail

    2. Ready for product review: Issue and proposal have the correct details for the review to begin

    3. Maintenance: Represents maintenance work

OSPR (Community Contributed Pull Request) management doesn’t include managing the product review process. However, OSPR managers may occasionally contact Product Submitters and/or Product Coordinators to inquire about details such as the current status of the product review process or the overall timeline for preparing a proposal for development.

  1. Share the proposal on the forum's Collaborative Proposals section for wider community feedback

  2. Find volunteers from any of the Product Working Groups to review the Product Proposal. You can find volunteers by:

    1. Posting a message on various Slack Product Working Group channels

    2. Joining various Working Group meetings and asking for help

  3. Select volunteers based on the following information:

    1. Recruit as many reviewers as you think necessary - more significant features require a greater number of reviewers

    2. Reviewers can be product experts, super-users, instructional designers, UX/UI designers, and other individuals qualified to evaluate the proposal

    3. While volunteers from the submitting organization can participate in the review process, at least one reviewer must be from an external organization

    4. The UX/UI team members can provide initial feedback, reserving detailed design reviews for proposals showing promising consensus for approval

    5. If the proposal includes significant alterations or discussions regarding infrastructure engage with a senior engineer for valuable input

If you encounter issues with a proposal, or struggle to find a reviewer, reach out to the Axim team by tagging @axim-product-team in the Product Core Working Group Slack Channel (#wg-product-core), or attend a Product Core meeting.

  1. Determine an appropriate time period for review, and communicate it clearly with all reviewers. To make collaboration easier, reviewers must add their feedback directly to the wiki page.

  2. Encourage reviewers to @ relevant people (i.e. Product / UX experts, developers, users etc.) to get a variety of feedback

  3. Communicate when the review period is over, so the Product Submitter can start incorporating feedback

Step 2. Product Coordinator Coordinates Reviews

  1. Review the GitHub issue and Product Proposal and make sure everything is clear and easy to understand

  2. Update and manage statuses on the GitHub issue as needed (e.g. apply the status directly or move it to the corresponding GitHub project column):

    1. [Prod Proposals] New: A newly submitted proposal that requires evaluation by the community.

    2. [Prod Proposals] On Hold: A proposal requiring additional information before it can proceed to the review stage.

    3. [Prod Proposals] Ready for Review: The GitHub issue and proposal contain all necessary details for the review process to begin.

    4. [Resourced] Backlog: The proposal has passed review, is funded, and has assigned design and development teams, but is awaiting implementation.

    5. [Not Resourced] Backlog: The proposal has passed review but lacks funding and/or assigned design or development teams, and is awaiting implementation.

    6. In Design: The design phase is in progress, including creating mockups, wireframes, and/or prototypes, with feedback being gathered.

    7. Being Developed: Development work has begun, based on completed designs.

    8. Shipped: The implementation is complete, and the product is delivered.

  3. Apply and change labels on the GitHub issue when/if necessary:

    1. Needs more product information: Issue and proposal need more detail

    2. Ready for product review: Issue and proposal have the correct details for the review to begin

    3. Maintenance: Represents maintenance work

OSPR (Community Contributed Pull Request) management doesn’t include managing the product review process. However, OSPR managers may occasionally contact Product Submitters and/or Product Coordinators to inquire about details such as the current status of the product review process or the overall timeline for preparing a proposal for development.

  1. Share the proposal on the forum's Collaborative Proposals section for wider community feedback

  2. Find volunteers from any of the Product Working Groups to review the Product Proposal. You can find volunteers by:

    1. Posting a message on various Slack Product Working Group channels

    2. Joining various Working Group meetings and asking for help

  3. Select volunteers based on the following information:

    1. Recruit as many reviewers as you think necessary - more significant features require a greater number of reviewers

    2. Reviewers can be product experts, super-users, instructional designers, UX/UI designers, and other individuals qualified to evaluate the proposal

    3. While volunteers from the submitting organization can participate in the review process, at least one reviewer must be from an external organization

    4. The UX/UI team members can provide initial feedback, reserving detailed design reviews for proposals showing promising consensus for approval

    5. If the proposal includes significant alterations or discussions regarding infrastructure engage with a senior engineer for valuable input

If you encounter issues with a proposal, or struggle to find a reviewer, reach out to the Axim team by tagging @axim-product-team in the Product Core Working Group Slack Channel (#wg-product-core), or attend a Product Core meeting.

  1. Determine an appropriate time period for review, and communicate it clearly with all reviewers. To make collaboration easier, reviewers must add their feedback directly to the wiki page.

  2. Encourage reviewers to @ relevant people (i.e. Product / UX experts, developers, users etc.) to get a variety of feedback

  3. Communicate when the review period is over, so the Product Submitter can start incorporating feedback

Step 3. Product Submitter Incorporates Review Feedback

  1. Make sure the Product Proposal incorporates relevant feedback received during the review period

  2. Document the intended roll-out plan with a committed development team

  3. Communicate with the Product Coordinator when the Product Proposal is ready for final approval

  4. Request that the Product Reviewers review the updated document and cast their final vote in the comment section on the wiki page

Step 3. Product Submitter Incorporates Review Feedback

  1. Make sure the Product Proposal incorporates relevant feedback received during the review period

  2. Document the intended roll-out plan with a committed development team

  3. Communicate with the Product Coordinator when the Product Proposal is ready for final approval

  4. Request that the Product Reviewers review the updated document and cast their final vote in the comment section on the wiki page

Step 4. Product Coordinator Manages Approval Process

  1. Gain Final Approval:

    A Product Proposal is approved if there are no outstanding objections from the:

    1. Core Product Working Group

    2. Product Reviewers

  2. Resolve Consensus Issues:

    1. If objections or concerns arise, the Product Coordinator can address and facilitate discussions to reach a consensus (there must be a 3 of 4 majority)

    2. If a consensus cannot be reached, the Product Coordinator will ask the Axim Product Team to make a final decision

    3. If there’s still disagreement, the Technical Oversight Committee (TOC) will have the final say

Future Consideration: The Core Product Working Group will determine if the proposal is part of the Core Product Offering or falls outside of it. This process needs further documentation, including criteria, evidence required, and necessary consensus.

  1. Change the GitHub issue’s:

    1. Label to “Product review complete”

    2. Status to “Backlog” or “Being Developed”

  2. Determine if an engineering or architecture review is needed (consult the Core Product Working Group if you’re unsure)

  3. [If needed] Refine the Proposal further, by adding:

    1. Additional user stories

    2. Usability testing plan

    3. Acceptance criteria testing plan

    4. Maintenance plan

  1. Once a proposal is approved, is in the GitHub Backlog and has a dedicated implementation team, add the project to the Community Release Sheet under the relevant spreadsheet tab.

Step 4. Product Coordinator Manages Approval Process

  1. Gain Final Approval:

    A Product Proposal is approved if there are no outstanding objections from the:

    1. Core Product Working Group

    2. Product Reviewers

  2. Resolve Consensus Issues:

    1. If objections or concerns arise, the Product Coordinator can address and facilitate discussions to reach a consensus (there must be a 3 of 4 majority)

    2. If a consensus cannot be reached, the Product Coordinator will ask the Axim Product Team to make a final decision

    3. If there’s still disagreement, the Technical Oversight Committee (TOC) will have the final say

Future Consideration: The Core Product Working Group will determine if the proposal is part of the Core Product Offering or falls outside of it. This process needs further documentation, including criteria, evidence required, and necessary consensus.

  1. Change the GitHub issue’s:

    1. Label to “Product review complete”

    2. Status to “Backlog” or “Being Developed”

  2. Determine if an engineering or architecture review is needed (consult the Core Product Working Group if you’re unsure)

  3. [If needed] Refine the Proposal further, by adding:

    1. Additional user stories

    2. Usability testing plan

    3. Acceptance criteria testing plan

    4. Maintenance plan

  1. Once a proposal is approved, is in the GitHub Backlog and has a dedicated implementation team, add the project to the Community Release Sheet under the relevant spreadsheet tab.

Step 5. Teams Execute Product Proposal

  1. Design relevant wireframes, prototypes, and user interfaces

  2. Discuss any deviations from the original Product Proposal with the Product Coordinator and/or Core Product Working Group

  3. Update the original Product Proposal to include details of the changes, justifications, and screenshots of new designs

  1. Link all pull requests to the corresponding Product Proposal GitHub Ticket to ensure traceability

  2. Follow the documented workflow for code changes - from proposal to merged code

  3. Update the original Product Proposal to include details of the changes, justifications, and screenshots of new designs

Step 5. Teams Execute Product Proposal

  1. Design relevant wireframes, prototypes, and user interfaces

  2. Discuss any deviations from the original Product Proposal with the Product Coordinator and/or Core Product Working Group

  3. Update the original Product Proposal to include details of the changes, justifications, and screenshots of new designs

  1. Link all pull requests to the corresponding Product Proposal GitHub Ticket to ensure traceability

  2. Follow the documented workflow for code changes - from proposal to merged code

  3. Update the original Product Proposal to include details of the changes, justifications, and screenshots of new designs

Definitions

A Product Proposal outlines a suggested modification to the Open edX platform. It can be submitted by an organization with a software team willing to implement the change or by individuals/groups without engineering resources. Clarity and detail in proposals are crucial for community comprehension and justification of the proposed change. Use the following Product Proposal templates for submission:

  1. Contribution solves a problem and includes a solution, or

  2. Contribution identifies a problem, but requires discovery

A GitHub issue, also known as a GitHub Ticket, closely resembles a Jira ticket, Trello card, or any other form of single-problem representation within an issue tracking system. We use GitHub because it’s public and free to use - browsing GitHub issues or boards doesn’t require an account. (A GitHub board mirrors a Jira or Trello board - offering a consolidated view of tickets.) For those new to GitHub, this tutorial could help you.

  • Product Submitter: Refers to the individual or group proposing a product for evaluation.

  • Product Core Working Group: Comprises of community members (open to all) who steer the development of the Open edX product. For more information, click here.

  • Product Coordinator: Oversees the product proposal review process, encompassing activities such as identifying reviewers, ensuring prompt reviews, engaging in feedback discussions with the Product Submitter, and providing comprehensive assistance to finalize the proposal.

  • Product Reviewer: An expert in the specific product area relevant to the proposal. For instance, a proposal focusing on enhancing the Discussions feature may involve reviewers such as instructional designers, course operators, UX/UI designers, or individuals with a social communication background.

  • Axim Team: The Axim team oversees the Open edX project, fostering community collaboration to build a leading educational platform. Axim team members actively engage in working groups and processes like Product Review. While they do not govern the platform (that's the community's role), they often provide support to resolve any project hurdles and ensure progress.

Access to GitHub

Anybody can create a GitHub issue, but only Open edX organization members can assign themselves to tickets or manage tickets on project boards. Product / Project Managers, and Working Group Members can gain access by following these steps:

  • Open this link

  • Select “🔐 GitHub Request - Access/Config”

  • Complete the form: enter your GitHub username and specify that you need "Triage Access Level" to aid your contributions to the Product Working Group

  • Please be sure to promptly accept your invitation as it expires in 7 days

 

 

Related content