Many people want to make contributions to Open edX that are larger than a single Open Source Pull Request (OSPR).  Often, these larger contributions touch several parts of the platform and require collaboration from multiple people inside and outside of edX.  To help keep track of these collaborations, and make sure we’re giving you the input you need, we’ve developed this process.

Throughout this document, we'll reference "the open source team".  That's the name of a group at edX whose job it is to grow the Open edX platform and community.  Currently it consists of Ned Batchelder, John Mark Walker, Matthew DuBose and Natalia Berdnikov.  You can reach all of us by emailing oscm@edx.org.  Once you've begun this process, your team will be assigned an open source team liaison.  That person will be your main point of contact throughout the process – if you're ever confused or have questions, please reach out to them.

If your changes are small enough to fit into an OSPR, you don't need this document - just go ahead and use our existing OSPR process.   Even if your charges are larger or more complicated, this process might not be the right fit for you.  If you'd like to skip some or all of these steps, get in touch with the open source team and we'll work something out.   If, on the other hand, you're not sure what kind of changes you want to make, you might not be ready to begin this process.  Again, please feel free to reach out to the open source team for help in making that determination.

This document assumes a fair amount of knowledge about how the Open edX platform and Open edX community work, but we're trying to make it as accessible as possible.  If you run into tools, processes or jargon that you don't know, please reach out to the open source team.  We're happy to help you get the lay of the land, and your feedback will help us improve this page.

Before You Begin

Before starting the contribution process, it's useful to take care of some basic logistics.  Many teams will have easy answers to these questions, or the questions won't be applicable to them.  That's fine! On the other hand, if you have difficulty answering these questions, you can always reach out to the open source team for help.

• Are you an official "working group"?
  
• Who are the members of your group?  

• How will you communicate about the project?

• How do you plan to conduct meetings (IRC, online video, phone, in person), and how often will you meet?

• How will you make decisions about the project (consensus, vote, leader makes final decision)?

• How should people outside of your group contact you with questions or to raise issues?

If you are a formal working group, please make sure to add your group's information to our working group directory.

Step 1: Goals

The goals of the contribution should be clearly stated.  To guide you in this process, we’ve created a template Goals Document.  Please fill out the document and send it to the open source team.

If you are having difficulty answering these questions, your goals are likely too undefined.  The edX open source team would be happy to help you refine your goals.  You can also see example goal documents below.

Involvement by edX: edX does not need to be involved until you submit the goals document, however we encourage you to let us know as soon as you get started, so we can help you align your goals with the overall project goals to help avoid any potential issues later. The product team, in particular, can provide advice on which goals may be more productive to pursue than others.  At some point during step 1, a member of the open source team will become your team's liaison.

Proceed to the next step when: you have filled out the goals document, sent it to oscm@edx.org, and received a go-ahead from the open source team.  Once the goals document is finished, it will be added to the Significant Contribution Index. 

Step 2: Design

The next step of the process is the design phase.  Here, you will make high-level architectural decisions which will help you meet the goals you formalized in Step 1.

The main output of the design phase is the Design Document.  The current template document is very product-focused, which may not be applicable for your contribution.  If the design document seems like a poor fit, we'll work together to adapt it to meet your needs.  You can see example design documents below.

As you articulate the design, you may find yourselves making architecture, style, and other kinds of decisions that could impact the community beyond the scope of your project.  If you find yourself making a decision like this, it’s important that you bring it to the community’s attention. This may be as informal as starting a thread on a mailing list.  It is possible however that you and/or other members of the community might want the decision formally discussed and recorded.  In that case, you and/or other members of the community would create Open edX Proposals (OEPs) to codify the changes. Generally speaking, having open OEPs should not prevent you from moving on to Step 3.

EdX has an accessibility team which reviews changes to the platform.  They can also be brought in to review design plans as needed.

Involvement by edX: The open source team and any relevant internal teams at edX should have been alerted to your proposed contribution by the end of Step 1 at the latest.  You should be communicating extensively with the relevant internal team at edX to create the design document, so that your design is compatible with the overall vision for Open edX.

Proceed to the next step when: Your open source team liaison will help you identify all of the internal teams which need to approve your design.  Once they've given you a thumbs up, the design document will be added to the Significant Contribution Index and you can continue to Step 3.

Step 3: Implementation Planning

In this step, you will plan out in detail your implementation of the design specified in Step 2. The main output of this phase is an implementation planning document.  We have provided a template document, the Implementation Planning Template. 

We recognize that teams may differ in how they prefer to communicate and plan.  Please check with the teams you're working with at edX that the template document works for them before going through the effort of filling it out.  If the team wants to modify the template, or use an alternate process, that's totally okay.

Unlike the goals and design documents, the implementation planning document will be a living document.  You should add links to OSPRs as you create them, and you may find that as you actually do the implementation (Step 4), that your plans change.  You do not need to seek formal re-review, but please make sure that your contacts at edX are getting notified of any significant changes.

Involvement by edX:  You should be communicating extensively with the relevant internal team at edX to create the implementation plan. 

Proceed to the next step when: Your team is satisfied with the implementation, and the internal edX teams who reviewed the design document have given you a thumbs up on the implementation planning document.

Step 4:  Implementation

In this final phase, you’ll implement the work detailed in Step 3.  Much of this work will involve the creation of OSPRs.  When submitting OSPRs that are part of a significant contribution, it’s helpful to reference the implementation planning document that the OSPR is being guided by.  Please also update the Implementation Planning Document to reference those OSPRs.  The open source team will reference the document to make sure your OSPR is sent to the right people for review.

If you haven't worked with a given team before, it's worth asking for guidance on how to navigate their contribution and review process, as different teams have different requirements for testing, code coverage, etc.  For instance, the TNL team has provided a thorough document called "Code Review Guidelines and Gotchas".

Involvement by edX:  Implementation will typically be driven by community members external to edX, with most or all of edX’s involvement coming via OSPR review. 

Proceed to the next step when:  When you're finished with implementation, please send a note to your open source team liaison so we can mark the work as resolved and upload the implementation planning doc to the Significant Contribution Index for future reference.  Congratulations, and thank you for your work! 

Significant Contribution Index

Add your contribution to the index, add links to in-progress documents, and upload finished documents on the Significant Contribution Index page.

Templates

Goals Document Template

Design Document Template

Implementation Planning Template

Other Resources

Use Cases for Significant Contribution is an in-progress page that should help give you an idea of how teams can move through this process.

Here are some example documents from work which predates this process, but which nevertheless may be useful:

• Content Tagging & Taxonomies “Product Thoughts” document - inspiration for the "Design Document" template
• Downloadable Learner Analytics Data - inspiration for the "Implementation Planning" template