Add node diagrams of where different bits of data are.

[wxtim]

This adds what I believe are helpful node diagrams of two of the forking models, and a less helpful diagram of the third (which is nonetheless illustrative).

See https://github.com/wxtim/git-working-practices/blob/node-diagrams_of_branch_modes/episodes/02-branching.md for the preview.

@astroDimitrios I've tried to build the docs locally, but the instructions seem to assume that I can sudo apt install. How do you preview changes when reviewing?

[astroDimitrios]

We will follow up the building locally offline with others in the Git and GitHub champions group if needed.

I wonder if instead of a flowchart diagram this should be a sequence diagram:

sequenceDiagram
    autonumber
    box Purple GitHub Remote
    participant GHM as origin main
    participant GHF as origin feature
    end
    box Blue Local
    participant M as main
    participant F as feature
    end
    GHM ->> M: git pull
    M ->> F: git switch -c feature
    loop Develop Changes
        F ->> F: git add <br/> git commit
    end
    F -->> GHF: git push
    GHF -->> GHM: Pull Request and then Merge
    GHM ->> M: git pull

Loading

[astroDimitrios]

https://github.com/MetOffice/git-github-docs/blob/main/review_process.md

[wxtim]

https://github.com/MetOffice/git-github-docs/blob/main/review_process.md

That's the review process workflow - what I'm trying to illustrate is the distributed nature of git. I think the concept of a potentially completely independent clone and living it's own life (until you push, pull or fetch) is alien to some of the people we saw on Wednesday.

What I'm really trying to communicate is that the branch structure is two generations deep - where svn has

trunk -- branchA
           |- branchB
            \- branchC

git has

clone -- branchA    # this might be the canonical copy, often called upstream
           \ branchB

# this might be your local copy
another_clone -- branchN
                           \- branchB [tracks clone.branch (note to self that the user may want this branch to follow that one)]

# Perhaps this is your fork on Github, but you could have pushed this up to a completely separate repo:
clone_on_gh -- branchF
 
# You can have clones anywhere!
clone_on_my_raspi -- branchX

[astroDimitrios]

Yes @wxtim sorry I pasted that there to also add in as I thought it might be useful, Emma sent it to me.

I will think about a diagram to represent this next week.
Perhaps we need to find a picture online which demonstrates distributed vs centralised version control

[wxtim]

Perhaps we need to find a picture online which demonstrates distributed vs centralised version control

First one found one a quick google - https://www.geeksforgeeks.org/centralized-vs-distributed-version-control-which-one-should-we-choose/

What I was aiming for with my diagram: https://medium.com/edureka/what-is-git-d7267d658069

[astroDimitrios]

Thanks @wxtim I can make versions of those for light and dark mode as svgs then add them in :)
Or I'll try and user Mermaid again to make them for me!

[wxtim]

Thanks @wxtim I can make versions of those for light and dark mode as svgs then add them in :) Or I'll try and user Mermaid again to make them for me!

Bear in mind that only really covers the branch model, but it's a reasonable template for the folk model

flowchart TD
    upstream --> |fork/sync| origin
    origin ==> |"PR (secure)"| upstream
    local --> |push| origin
    origin --> |switch/checkout| local

Loading

(What many people actually do)

flowchart TD
    upstream --> |switch/checkout| local
    local --> |push| origin
    origin ==> |"PR (secure)"| upstream

Loading

or for more context (adding numbers to indicate the order of steps)

flowchart LR
    subgraph GitHub
        origin ==> |"❸PR (secure)"| upstream
    end
    upstream --> |"❶switch/checkout"| local
    local --> |❷push| origin
    subgraph "My Computer"
        local
    end

Loading

[wxtim]

A complex model which might mention to people just to show how powerful this approach is:

flowchart LR
    subgraph GitHub
        origin ==> |"❸PR (secure)"| upstream
    end
    upstream --> |"❶switch/checkout"| local2
    local2 --> |❷push| origin
    local --> |❷push| origin
    upstream --> |"❶switch/checkout"| local
    upstream --> |"git switch (daily backup)"| metomi
    subgraph "My Computer"
        local
    end
    subgraph pi ["my raspberry pi"]
        local2
    end
    subgraph _metomi["Metomi team machine"]
        metomi
    end

Loading