Git repo setup flowchart

The proposed git workflow for the AMI stack is based on The GitHub Flow.

In order to set up suitable remote and local Git repositories for yourself, for any given module within the AMI stack (e.g. euclid, or svg), please follow this flowchart.

Editable PlantUML code for above diagram:

@startuml
skinparam dpi 150

start

  :Ensure you are logged in to GitHub;

if (You already have your own Git remote for that AMI module) then (no)
  :Browse to the GitHub page for that module\n(e.g. __https://github.com/ContentMine/svg__;
  :Click the "Fork" button (near top right);
  :If GitHub asks you where to fork it to,
   select your user account;
  :Wait for forking to complete;
else (yes)

  if (The remote in your namespace has
      the name you want it to have) then (yes)
  else (no)

    if (The remote in your namespace
        has machines visiting its URL,
        so that URL must not change) then (yes)
      :Perform switcheroo.
       TODO: document this}
    else (no)
      :If you are not already there,
       browse to the GitHub
       page for your own remote, e.g.
       __https://github.com/petermr/svg__;
      :Click the "Settings" tab;
      :Edit the "Repository name"
       field to the appropriate
       new value, and click "Rename";
    endif

  endif

endif

  :If you are not already there, browse to the GitHub
   page for your own remote, e.g.
   __https://github.com/petermr/svg__;
  :Click the "Clone or download" button;

if (You normally push to GitHub via) then (SSH)
  :In the drop-down, ensure that **Clone with SSH** is
   stated and the URL begins __git@github.com:...__;
else (HTTPS)
  :In the drop-down, ensure that **Clone with HTTPS** is
   stated and the URL begins __https://github.com/...__;
endif

  :Copy the URL to the clipboard;

if (You already have a local repository to which you want to add //your// remote) then (no)
  :Use your CLI to (create and) navigate to the
   directory where you want to clone that remote;
  :At your CLI, run **//""git clone <url>""//**, pasting
   the URL in place of **//""<url>""//**;
  :Rename your own remote from "origin" to your
   initials, e.g. **//""git remote rename origin pmr""//**;
else (yes)
  :Use your CLI to navigate to that local repository;
  :Ensure you do not already have a remote named after
   your initials (e.g. run **//""git remote""//** to check);
  :At your CLI, run **//""git remote add <initials> <url>""//**,
   where **//""<initials>""//** are your initials (e.g. **//""pmr""//**)
   and **//""<url>""//** is the URL you copied;
endif

  :Run **//""git remote --verbose""//**;

if (Your local repository is aware of ContentMine's remote,
   e.g. __https://github.com/ContentMine/svg.git__) then (no)
  :Browse to the ContentMine GitHub page for that module, e.g.
   __https://github.com/ContentMine/svg__;
  :Click the "Clone or download" button;
  :In the drop-down, ensure that **Clone with HTTPS** is
   stated and the URL begins __https://github.com/...__;
  :Copy the URL to the clipboard;
  :Run **//""git remote add origin <url>""//**, pasting the
   URL you copied;
else (yes)
  if (Your local repository calls it "origin") then (no)
    :Rename that remote to "origin" from its existing name,
    e.g. **//""git remote rename <existingname> origin""//**;
  else (yes)
  endif
endif

  :Ensure that all your local and remote branches have the desired names.
   In particular, merge or rename any branches on your personal remote
   that would otherwise block pushes due to conflicting changes. Detailed
   instructions for doing so are out of scope for this flowchart.}
  :When you have made commits that you are ready to
   push, use **//""git push --set-upstream pmr""//**,
   substituting your initials as appropriate;
  :Thereafter, you can omit the **//""--set-upstream""//**
   and simply use, e.g.: **//""git push""//**;

stop



@enduml