Merge branch 'mirroring' into 'master'

howTo: mirroring and SVE

See merge request SERG/workflow!15

howTo/mirroringRepositories.md

+# Mirroring repositories in Gitlab
+
+Author: Tom Rushby (@tom_rushby)
+
+Gitlab has a useful page on mirroring: https://docs.gitlab.com/ee/user/project/repository/mirror/
+
+## Gitlab to GitHub mirror
+
+i.e. you want to create a copy of a repository in the University Git service on GitLab.
+
+In this case we create a *push mirror*: a downstream repository (on GitHub) that mirrors the commits made to the upstream repository (on Gitlab).
+
+Creating a mirror allows a repository with restricted access to be publically availble (and backed-up on another platform), as well as taking advantage of functionality on GitHub such as pages (currently not available on the Univeristy implementation of GitLab).
+
+It's not terribly clear on the page linked above, but you will need to generate an Access Token within your GutHub account. This will be use as the password in the mirroring section of the repo on GitLab (git.soton.ac.uk). https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+
+## Step-by-step
+
+1. Create a clean (target, or 'downstream') repository in your GitHub account. I use the identical name as the repo in GitLab and add (mirror) in the description to indicate that it is a mirrored copy.
+2. Copy the https URL to the repo e.g. `https://github.com/mygitaccount/myrepo`
+3. In the **Gitlab** (source, or 'upstream') repository to be mirrored, goto > `Settings` > `Repository` and expand the `Mirrroring repositories` section. Enter the GitHub repo URL but in the format `https://gitusername@github.com/gitusername/reponame`.
+4. Go back to **GitHub** and and [create a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). In the top right corner. click your profile photo, and click **Settings**. On the Settings page, click **Developer settings** (at the bottom of the left-hand sidebar). Click **Personal access tokens** in the left sidebar and then **Generate new token**. When generating the access token you will need to tick the boxes to allow "repo" and "workflow" permissions. Once complete, copy the access token to the clipboard.
+5. Now in **Gitlab**, paste the access token into the **Password** field and click the **Mirror repository** button. The repository should now appear in the Mirrored repositories list with 'Push' as the direction. Each time a commit is made to your Gitlab repository  it will be automatically pushed to the mirrored repository downstream. Clicking the 'Update now' button in the right-hand column of the list will force the push and is useful to test the process when setting up. If the process fails, errors will be shown in the list under 'Last successful update'.
+6. Commit to your Gitlab repo and watch your GitHub copy update automatically. Magic!

howTo/sve.md

@@ -6,9 +6,9 @@ A windows [virtual desktop](https://sotonac.sharepoint.com/teams/IT/SitePages/Se
 
 The SVE offers two services:
 
- * Win 10 Student service - this one has research & academic software suites such as RStudio etc. But it does **not** have persistence. This means that any packages you install or any repos you clone into your local space will vanish when you log out. The only expection is if you:
+ * Win 10 Student service - this one has research & academic software suites such as RStudio etc. But it does **not** have persistence. This means that any packages you install or any repos you clone into your local space will vanish when you log out. The only exception is if you:
     * clone the repos to your MyDocuments/OneDrive account
-    * work out how to use your Windows profile to 'host' the packages
+    * work out how to use your Windows profile to 'host' the packages (or do some nifty work with the `renv` package)
  * Win 10 Staff service - this is a generic staff service intended for admin & professional staff use (for now). While it **does** have persistence, it does **not** have RStudio installed...
  
 ## Why would I use the SVE?
@@ -25,9 +25,13 @@ But:
 
 ## Git
 
-Git is installed - yay!
+Git is installed on the SVE - yay! You do know how to use Git, right?  No? [try starting here](https://happygitwithr.com/index.html).
 
-You will need to create your RSA key so that git (inside or outside RStudio) can talk to github/gitlab etc. This RSA key should now be persistent (it didn't used to be before the SVE upgrade).
+### Git authentication
+
+HTTPS vs SSH? It's up to you but [some argue](https://happygitwithr.com/https-pat.html#https-vs-ssh) that HTTPS is easy to get you going.
+
+Whatever, you will need to authenticate the SVE (local machine) with Gitlab/GitHub. You can do this via HTTPS, entering your username and password in each session on the SVE (not a big deal)... or by using an RSA key. This RSA key should now be persistent on the SVE (it didn't used to be before the SVE upgrade). 
 
 ## RStudio in SVE
 
@@ -38,3 +42,29 @@ If you need to add new packages use the install.packages() function. This seems
 
 Better yet use the [loadPackages() function](https://git.soton.ac.uk/SERG/workflow/-/blob/master/R/loadLibraries.R) developed at SERG :-)
 
+Even better, consider using the `renv` package. More on this coming soon.
+
+### Using Git within RStudio
+
+We recommend storing your local (working) project repositories within your `Documents` folder on the university filestore as [storing Git repositories within cloud-synced folders may cause problems.](https://andreashandel.github.io/MADAcourse/Tools_Github_Introduction.html#GitGitHub_and_other_cloud_based_sync_options)
+
+Git does seem to have some weird behaviour on the SVE to be aware of ... the correct operation of Git witin RStudio on the University network requires some careful working practices with respect to file paths.
+
+Using the University filestore for project (working) files requires use of the mapped file path `filestore (H:)` _<u>not</u>_ the `Documents` shortcut in the `Quick access` group of Windows Explorer.
+
+While these two paths refer to the same physical location for your documents folder, they are resolved differently i.e. `H:\` vs `\\filestore.soton.ac.uk\users\xxmyusernamexx\mydocuments`. When a project is started in RStudio from the latter location, the Git repository is not recognised correctly. As a result, the `Git` tab will be missing from the Environment pane.
+
+Loading a project from `Documents` in `Quick access` group, the figure shows no `Git` tab and thus no access to Git processes thru the RStudio IDE:
+
+![Environment Pane, My Documents](img/rtools_env_pane_mydocs.png)
+
+Loading project from the same folder via `H` (mapped drive), figure shows the `Git` tab is now present and Git commands now accessible:
+
+![Environment Pane, H](img/rtools_env_pane_h.png)
+
+This problem seems to be limited to the Environment pane within the RStudio IDE as running Git commands through the Terminal (Console pane) pick up the repository correctly (as shown in image below).
+
+![Terminal Pane](img/rtools_terminal_pane.png)
+
+So using Git through the Terminal is unaffected by the path used to open the project.
+