Development with Forks

Cheat-sheet showcasing a workflow using forks, and feature branch development within the fork. See the Branching Models: Forking section for more information.

Summary Diagram

---

sequenceDiagram
    accDescr {A sequence diagram showing the steps for using
    Forks with the branching model.}
    autonumber
    participant UM as upstream main
    participant GHM as origin main
    participant GHF as origin feature
    participant M as main
    UM ->> UM: #f
    Note over UM: Open an Issue for the change
    UM -->> GHM: #f
    Note right of UM: First time: Fork the repository
    GHM -->> M: #f
    Note right of GHM: First time: git clone<br/>Then: git pull
    create participant F as feature
    M ->> F: Create a feature branch:<br/>git switch -c feature
    loop
        F ->> F: #f
        Note over F: Develop changes:<br/>git add<br/>git commit
    end
    F -->> GHF: #f
    Note left of F: Push to GitHub: git push<br/>The first push creates origin feature!
    destroy GHF
    GHF -->> UM: #f
    Note left of GHF: Pull Request and then Merge.<br/>Delete origin feature branch.
    UM -->> GHM: #f
    Note right of UM: Sync your fork
    GHM -->> M: #f
    Note right of GHM: git pull
    Note over F: Delete branch:<br/>git branch -d feature
    box Met Office Repo - GitHub
    participant UM
    end
    box Your Fork - GitHub
    participant GHM
    participant GHF
    end
    box Your Working Copy - Local
    participant M
    participant F
    end

Code Example

---

1. Open an Issue for the change on the upstream repository (Met Office repository)

2. First time only: Fork the repository on GitHub by selecting the Fork button on the upstream repository homepage. See the Create a Fork section for more information.

3. Clone your fork or update your local fork

   First time only:

   BASH

   git clone <repository-ssh-url>
   cd <repository-name>

   Then after:

   BASH

   git switch main
   git pull

4. Create a feature branch

   BASH

   git switch -c <branch-name>

5. Develop changes

   BASH

   git add <files>
   git commit -m "Commit message describing the change"

6. Push to GitHub

   BASH

   git push

7. Open a Pull Request ensuring the target is the upstream Met Office repository. Progress through the review process, and delete the origin feature branch on your fork when the PR is merged.

8. Sync your fork

   This covers steps 8 and 9 in the diagram, which can be done either via GitHub or the command line.

   Use the command line option below if you are resolving merge conflicts as part of the development or review process.

   Via GitHub

   Via the command line

   On GitHub, navigate to your forked repository and select the Sync fork button.

   

   Then update your local copy:

   BASH

   git switch main
   git pull

   Switch to the main branch:

   BASH

   git switch main

   Add the upstream repository as a remote if you haven’t already:

   BASH

   git remote add upstream <upstream-repository-ssh-url>

   Fetch the latest changes from the upstream main branch:

   BASH

   git fetch upstream

   Merge the changes into your local main branch:

   BASH

   git merge upstream/main

   Then update your fork on GitHub:

   BASH

   git push

:::

10. Delete the local feature branch in your fork

BASH

git switch main
git branch -D <branch-name>