Version control: Git + GitHub

Code belongs in Git, data belongs in SharePoint — both must outlive the analyst who wrote them

GitHub is the shared space

Organization	Status	What to do with it
github.com/worldbank	Managed by the World Bank. The way forward.	All new code and new projects.
github.com/wbepl	Legacy platform, not managed by the WB.	Phase out. Read legacy code only.

WarningTwo rules, no exceptions

1. New repositories are created under github.com/worldbank, never under github.com/wbepl.
2. Every repository you create gets the MML team added with the Maintain role, so the work survives your departure.

The four verbs

Four commands cover the whole daily cycle. Everything else in Git is a refinement of these.

clone

Make a local copy of a repository that already exists on GitHub. Once per repository, per machine.

commit

Save a snapshot of your changes — one line, one file, or many — with a message describing what changed.

push

Upload your commits to GitHub, where they are backed up and visible to the team.

pull

Bring other people’s commits down from GitHub into your local copy.

If you use the Source Control view in Positron/VS Code, or GitHub Desktop, instead of the command line, the buttons are labelled with these same four words and do exactly the same thing.

TipLearn the commands by running them

This page is the rulebook: which organization, which template, who gets access, how repositories are named. It deliberately does not teach the commands.

The hands-on walkthrough — configure Git, start or clone a repository, stage, commit, push, and read history on GitHub — is the exercise Git and GitHub: your solo workflow. Work through it once, then come back here for the MML-specific rules.

Commit messages are documentation

A commit message is the only place where the reason for a change is recorded. The diff already shows what changed; it can never show why.

TipWrite for the analyst who inherits this in 2030

That analyst will read your commit log to answer one question: “why is this number different from the published one?” update, fix, and changes answer nothing. Rebase weights to 2021 census totals answers it in five words.

Write in the imperative, name the object, give the reason when it is not obvious.

The collaboration layer

Once more than one person touches a repository, five more terms come into play.

remote

A repository hosted on a server, e.g. GitHub, GitLab or Bitbucket. origin is the default name for the one you cloned from.

branch

A parallel version of the code that diverges from the main line of development. Work on a branch when a change might break something others depend on.

pull request

A request to merge one branch into another. This is where code review happens — someone else reads the change before it lands.

merge

Combine the changes from one branch into another, resolving any conflicts that arise.

fork

A personal copy of someone else’s repository under your own account, so you can change it without touching the original. Mostly needed for contributing to projects you do not have write access to.

The recovery layer

Commits are the only points you can return to. That is the reason to commit often.

diff

A comparison between two versions of a file, showing what was added, modified, or removed.

revert

Undo a previous commit, restoring the code to its earlier state — as a new commit, so the history of the mistake is preserved too.

Reading diffs, comparing two commits, and tracing a single line with blame are all practised in the solo-workflow exercise.

Tooling

Git runs on your machine; GitHub is where the shared copy lives. You need both, and the local half is not optional.

On your PC. Install Git for Windows from the WB software center — no admin permissions required. Then drive it either from the command line or through a graphical client:

• Positron / VS Code — the recommended one. Positron is already the MML editor (see Recommended software), and its Source Control view stages, commits, pushes, pulls, shows diffs and resolves conflicts without leaving the file you are editing. Nothing to install: it appears as soon as the folder is a repository. Reference: VS Code — Source Control overview.
• GitHub Desktop, also in the WB software center, no permissions required — a separate window, useful if you prefer Git kept apart from the editor.
• Any other editor with Git integration, e.g. RStudio.

On GitHub. Every change that matters gets pushed to the remote repository. That is what makes the work backed up, reviewable, and inheritable — a commit that lives only on your laptop protects nobody.

Onboarding: one-time setup

Do this once, when you join the team.

• Request access to the WB GitHub organization: Join WB GitHub
• Ask to be added to the MML team: https://github.com/orgs/worldbank/teams/mml
• Read the World Bank Open Source rules: https://github.com/worldbank/ospo or https://worldbank.github.io/ospo
• Work through Git and GitHub: your solo workflow end to end — it sets your Git identity and drills the four verbs on a throwaway project.

NoteAccess to the OSPO links

You must have access to github.com/worldbank and be logged in to open these links.

The OSPO documentation covers how to contribute, the licensing and WB Rider requirements, and how to make a repository public — which requires a review first.

Starting a new project

Do this once per repository.

• Create the repository under https://github.com/worldbank from the mmlTemplate template. The template ships a README.md, a .gitignore, a LICENSE and a WB Rider — all four are prerequisites for ever making the repository public.

• Pick a unique, simple name (see the rules below).

• Add the MML team as Maintain.

  • Settings > Collaborators and teams > Add teams > select MML > role Maintain.
  • Direct link: https://github.com/worldbank/<repository-name>/settings/access

• Fill in About and Topics — the gear icon in the About section of the repository page. A one-line description and a few topics are what make the repository findable by someone who does not know it exists.

• Edit the README and replace every placeholder.

Naming rules

• If the project is country-specific, start with the ISO code of the country in small letters.
• Follow with what the repository is about: capitalize the first letter of each word, or use an all-capitals acronym. No spaces, no special characters.
• End with the fiscal year if the work is tied to one.
• Examples: gnbFIA2026 — Guinea-Bissau Fiscal Incidence Analysis FY 2026; colMM2024 — Colombia Macro-Micro Simulation FY 2024.