Merge Guidelines for Coding Core Contributors
- Kyle McCormick
- Brian Mesick
- Ned Batchelder (Deactivated)
- Robert Raposa
2U employees: Please keep this page up to date! It will help the community help you by making informed decisions about merges that will affect edX production environments.
Core contributors: Please consider these guidelines in conjunction with those listed in CC reviews and ownership.
Background
Two groups of individuals have merge rights to the openedx GitHub organization:
Core Contributors in the Coding role (including Axim engineers), and
Employees and contractors of 2U, who operate edx.org.
2U, unlike most other Open edX operators, ships code directly off of the master branch of Open edX service repositories. This helps them rapidly iterate on features and fixes. It also helps the community by ensuring that Open edX code is immediately battle-tested in a massive-scale environment.
This means that breaking changes and bugs will impact 2U shortly after merge, whereas they impact most community members on the 6-month release cycle. So, we encourage CCs and 2U operators to work together, so that CCs can easily merge PRs to master in a way that 2U operators can anticipate and respond to if there are bugs.
General requirements
Merges to master must using defensive CI/CD techniques such as feature toggles, where applicable.
Guidelines for edx-platform
When is edx-platform deployed? | edx-platform and openedx/configuration are continuously deployed to edX production. Upon merging a pull request, edx-platform is generally released to the Staging environment (courses.stage.edx.org) within one hour and the Production environments (courses.edx.org and edge.edx.org) within two hours. Furthermore, openedx/configuration contains tools and scripts that may have immediate impact on edX’s Staging and Production deployment pipeline. |
|---|---|
What is the ideal merge window? | Monday through Friday, between 7:30 AM and 3:30 PM, Eastern US (NYC/Boston) Time.
|
What should I do before merging? | Inform the relevant
Sample post: “I plan on merging |
How do I know when I can merge? | If your lead time on your Slack announcement has elapsed, you can merge. Or, if someone from 2U let’s you know it is ready-to-go, you can immediately merge. This may come in the form of an emoji like: or . Do not immediately merge with the emoji , which may mean someone is looking, but has not yet confirmed all is well. |
What if something goes wrong with my code? | Your PR may cause a bug in edX production, break tests on The 2U engineer should follow up shortly with an explanation of what broke and provide any info they have about why it broke, such as logs or screenshots. When you are ready, follow the normal process again to reintroduce a fixed version of your PR. |
Are there other times merging is discouraged? | Weekends. Saturdays and Sundays. |
Christmas and New Year’s Day (12/25 and 1/1). In some years, 2U requests a broader merge freeze between 12/22 and 1/4. Reach out to your the correct Slack channel if you want to merge within this time period. | |
Martin Luther King Jr. Day. The third Monday of January. | |
US President’s Day. The third Monday of February. | |
US Memorial Day. The last Monday of May. | |
Juneteenth. June 19th, or the weekday nearest to it. | |
US Independence Day. July 4th, or the weekday nearest to it. | |
US Labor Day. The first Monday in September. | |
Indigenous Peoples’ Day. The second Monday in October. | |
Veteran’s/Armistice Day. November 11th, or the weekday nearest to it. | |
Thanksgiving + day after. The fourth Thursday and Friday in November. | |
Additional special dates may come up. Please watch this page if you plan to merge code! |
Guidelines for other repositories
When are other repositories deployed? | Frontend app repositories (ie “MFEs” / “micro-frontends”) are generally deployed to edX production manually by the owning team at 2U. |
|---|---|
Backend service repositories (ie “IDAs” / “independently deployable apps”) are generally deployed to edX production manually by the owning team at 2U. | |
Python and JavaScript packages are “deployed” when they are upgraded in their respective service repositories. Because different services upgrade dependencies at different rates, the lead time from merging to production here can vary. To minimize this lead time, we recommend to quickly follow each package merge with (1) a package release and then (2) an upgrade of that package in at least one service. When upgrading the package in a service, follow that service’s merge timing guidelines. | |
Dev tools such as Devstack are not “deployed” per se, but merged changes are immediately apparent to developers once they | |
What is the ideal merge window? | You can merge to these repositories whenever you want to once you have met that repository’s review requirements. |
What should I do before merging? | Non-2U merges to frontend apps: Inform Non-2U merges to other repos: Nothing 2U merges: inform the owning team. Depending on the repository, you may need to kick off a production deployment. |
What if something goes wrong with my code? | Your PR may cause a bug in edX production, break tests on
Keep in mind that 2U engineer may need you to take option (1) depending on their operational needs. |
Are there other times merging is discouraged? | At the moment, no, but please watch this page if you plan to merge code! |