This issue is to allow us to analyse what we need to do to migrate the Moodle repository's "master" branch to "main". The aim is to have an idea about the timeline and be able to determine when we can achieve this so we can set expectations for the community.

Implementation plan

Here it's the plan regarding the transition from "master" to "main" to be applied to all Moodle (LMS) related repositories. It includes all the information available and the the agreed outcomes coming from different sources (meetings, discussions...).

Basic requirements

• The plan must be designed in the less breaking/impacting possible way, allowing to everybody (internal and external) to apply for the changes easily and over a "good enough" period of time.
• The plan is dynamic, open be amended when needed, specifically all the items (actions) to be executed on each phase.
• The plan will be publicly available, and communications at all levels (overall, technical, docs...) will happen regularly.
• The plan needs to be trackable, with a clear list of items to be processed, what's pending and done, who is on each item, where to find more information... and easy to add new items.
• MDLSITE-7418 will be the main issue to share, discuss, propose anything related with the plan.

Technical justification

Because the plan execution is going to take long, and specially because there are multiple items that we (Moodle HQ) don't control - specifically all external clones, forks and plugins in planet Earth and beyond... - and, also, because of the requirements listed above, the plan more important point is to ensure that both the "master" (current) and "main" (future) branches will coexist for a long period of time (until August 12th 2024).

At the very end of the plan execution the "main" branch will become the current branch, with "master" becoming the "old" branch, ultimately being removed from all Moodle (LMS) repositories and official clones.

Of course, while both branches are coexisting, it will be guaranteed that they are 100% on-sync (pointing to exactly the very same commit / HEAD) along the whole plan execution.

Plan execution phases

Phase 0: Preparations

This phase includes all the preliminar discussions, agreements, early tests and internal requests aiming to:

• Draft a plan (this one), open to modifications.
• Collect all the changes (actions) together to have them at hand and track progress (this issue description, subtasks if needed...)
• Perform various tests, checking for the viability of maintaining the 2 branches available over a long period of time (until August 12th 2024).
• Once the plan is agreed, perform the first official communications (internal & external).

This phase will (estimated) run over 3-4 weeks. Mostly Moodle HQ only, but with possible inputs from everywhere else.

Phase 1: Integration repositories and processes migration

An alternative way to see this phase is to understand it like the "writing phase", in which all the processes related with sending information (write) to the repositories are migrated to the new branch.

Luckily, there aren't many processes writing to repositories. In fact, there are only a couple of them, both 100% managed by the integration team:

1. The manual integration process, where Moodle (LMS) changes are accepted and become part of the integration.git repository.
2. The rolling / release process, where versions and other small bits are adjusted and changes are sent to all upstream repositories.

So, at the end of this phase we'll need to guarantee that:

• All the processes above are performed against the new "main" branch.
• The "master" branch is always kept 100% on-sync with the "main" branch.
• All the changes are populated to moodle.git repository and official clones.
• "main" becomes the default branch in all those repositories.
• The existence of the new "main" branches is communicated, together with the beginning of the (next) phase.

This phase will (estimated) run over 3-4 weeks. Overall, it only affects to Moodle HQ (more specifically to the Integration Team - iTeam).

Phase 2: Upstream repositories, integrations, tools and plugins migration

This is the "hodgepodge" phase, where everything else is moved from the old "master" branch to the new, already existing, "main" one. With other words, this is the "reading phase" where all the clones, forks, integrations, tools and plugins using the moodle.git repositories need to be migrated.

For Moodle HQ it means a lot of (tiny) changes to be applied in an, undetermined yet, number of places and now it is when the collected list of actions becomes important.

At the end of this phase we'll need to guarantee that:

• Moodle HQ has performed all the the needed migration actions.
• The "master" branch is always kept 100% on-sync with the "main" branch.
• Communications have happened, both internal and external, helping and supporting people with the migration.
• Everything is working perfectly against the new "main" branch.

This phase will (estimated) run over no less than 2 months (Xmas break coming). It affects to Moodle HQ (everybody, everywhere within the org using moodle.git repos) and to the whole Moodle Community, all levels.

Phase 3: Final steps, wrapping up and ciao

After some time, on August 12th 2024, the incoming/soon/imminent/confirmed removal of the old "master" branch from all moodle.git repositories will happen. The plan will be, then, considered "complete".

Extra checks, reviews, retros/day after, wrapping up actions may happen in this phase.

Hopefully, everybody will be happy with the brand-new "main" branch. Goal achieved and party.

This phase will (estimated) run over 1-2 weeks, it is performed by Moodle HQ and will affect to everybody (internal and external) that has not been able to proceed with the migration. Hence, the repeated communications in this phase are really important.

List of actions

• ✅ Initial communication (link).
• ✅ CI and tooling
  • We need to prepare our CI to be ready for the main branch and eventually point the jobs that use the master branch to the main branch.
• ✔️ Testers environment.
• We need to prepare our tooling and eventually switch to the main branch.
  • 🚧 core
    • ✅ GHA integration
    • 🚧 own core stuff (moodle_database, config-dist, ...) => MDL-80179
  • ✅ mdlrelease
  • ✔️ serverscripts
  • ✔️ moodle-local_downloadmoodleorg
  • ✅ moodle-performance-comparison
  • ✅ moodle-docker
  • ✅ moodle-ci-runner
  • ✅ phpdoc
  • jsdoc
  • ✅ nightlyjobs
  • ✅ moodle-local_ci (general, security rebaser, cibot and tobic)
  • ✅ moodle-local_codechecker
  • ✅ moodle-local_moodlecheck
  • ✅ moodle-plugin-ci
  • ✅ moodle-cs
  • ✅ tracker configuration
  • ✅ jenkins configuration
• Third-party tools
  • ✅ MDK
  • ✔️ AMOS
  • All clones / forks out there with any process built on it.
  • All plugins having any CI integration with core. Own and 3rd part.
• Repositories
  • ✅ Create the main branch for moodle.git, integration.git, security.git
  • Other repositories that may be using the master branch? (Apps, WP, Cloud, etc)
• Documentation
  • ✅ devdocs (old and new)
  • ✔️ GDocs
• Sites
  • ✔️ Prototypes
  • ✅ QA, demo...

Pictograms used above:

• ✔️: The element has been added to the list of actions to perform. Not completed yet.
• 🚧 : Works on the element have started.
• ✅ : The element has been completed.