Add Gitlab as an alternative to GitHub (ref #535)

.gitignore

@@ -2,6 +2,7 @@ _build/
 build/
 .ipynb_checkpoints
 /venv*
+/.venv/
 .jupyter_cache
 jupyter_execute
 /content/__pycache__/

content/configuration.md

@@ -6,11 +6,11 @@ We have a longer version of this in the [installation
 instructions](https://coderefinery.github.io/installation/git-in-terminal/).
 But for clarity, we will review the most important parts here.
 
-You don't need to set these if you work only through the GitHub web interface.
+You don't need to set these if you work only through the GitHub or GitLab web interface.
 If you use VS Code or other editors or integrated development environments,
 the editor might prompt you to set these up. If you use RStudio, you can carry 
 out the configuration in RStudio (see the RStudio tab in the section [Authenticating 
-to GitHub](https://coderefinery.github.io/git-intro/configuration/#authenticating-to-github-ssh-or-https-or-vs-code)
+to GitHub or GitLab](clone-method)
 below).
 
 These configuration settings are saved in a file called `.gitconfig` in your
@@ -34,11 +34,17 @@ $ git config --global user.name "Your Name"
 $ git config --global user.email yourname@example.com
 ```
 
-For the email address we recommend to use the one you use for your GitHub account.
-If you prefer to not use it, you can instead use
-`YOUR_GITHUB_USERNAME@users.noreply.github.com` as the email address (replace `YOUR_GITHUB_USERNAME`).
-This means that nobody can write to this email address, but GitHub will still
-be able to connect your contributions with your GitHub account.
+For the email address we recommend using the one associated with your GitHub
+or GitLab account. If you prefer not to expose your personal email address,
+you can instead use the privacy-preserving no-reply address provided by the
+service:
+
+- GitHub: Copy the exact address shown in your [email settings](https://github.com/settings/emails).
+- GitLab: In your profile settings, select **Use a private email** as the commit email and copy the generated address.
+
+The address may contain an account-specific ID, username, or other details, so
+do not try to construct it yourself. This allows the service to connect your
+contributions with your account without exposing your personal email address.
 
 Note that these can, in theory, be anything: this is just data, not a
 registration or identity requirement.
@@ -84,9 +90,9 @@ to set other editors, or do a web search for "git set editor to
 % This anchor used for linking from other lessons
 (clone-method)=
 
-## Authenticating to GitHub: SSH or HTTPS or VS Code or RStudio?
+## Authenticating to GitHub or GitLab: SSH or HTTPS or VS Code or RStudio?
 
-**How does GitHub know who you are?** We discuss here four options:
+**How does the hosting service know who you are?** We discuss here four options:
 - **SSH** is the classic method, using [Secure Shell
   Protocol](https://en.wikipedia.org/wiki/Secure_Shell) remote connection
   keys.
@@ -104,7 +110,9 @@ Test which one you should use:
 
 :::::{tabs}
   ::::{group-tab} Command line: SSH
-    Try this command:
+    Try one of these commands, depending on where your repository is hosted:
+
+    **GitHub:**
     ```console
     $ ssh -T git@github.com
     ```
@@ -113,13 +121,21 @@ Test which one you should use:
     then SSH is configured and the following steps will work with the SSH
     cloning.
 
+    **GitLab:**
+    ```console
+    $ ssh -T git@gitlab.com
+    ```
+
+    If it returns `Welcome to GitLab, @USERNAME!`, then SSH is configured
+    and the following steps will work with SSH cloning.
+
+    From now on, **if you know that SSH works, select SSH as the clone URL
+    from the service hosting your repository.** GitHub URLs start with
+    `git@github.com:` and GitLab URLs start with `git@gitlab.com:`.
+
     See our [installation
     instructions](https://coderefinery.github.io/installation/ssh/) to
     set up SSH access.
-
-    From now on, **if you know that SSH works, you should always select
-    SSH as the clone URL from GitHub, or translate the URL to start with
-    the right thing yourself:** `git@github.com:` (with the `:`).
   ::::
 
   ::::{group-tab} Command line: HTTPS
@@ -133,32 +149,32 @@ Test which one you should use:
     you try using it).
 
     From now on, **if you know that HTTPS works, you should always select
-    HTTPS as the clone URL from GitHub, or translate the URL to start with
-    the right thing yourself:** `https://github.com/`
+    HTTPS as the clone URL from your hosting service, or translate the URL
+    to start with the right thing yourself:** `https://github.com/` or
+    `https://gitlab.com/`
   ::::
 
   ::::{group-tab} VS Code
-    VS Code has its own authentication method and the editor will guide you
-    through the process. If you are using VS Code, you can skip the SSH and
-    HTTPS checks.
+    VS Code has its own authentication method for GitHub and GitLab
+    integrations, and the editor or its extension will guide you through the
+    process. If you are using VS Code, you can skip the SSH and HTTPS checks.
 
     From now on, you should **select HTTPS as the clone URL from
-    GitHub, or translate the URL to start with the right thing
-    yourself:** `https://github.com/`
+    GitHub or GitLab, or translate the URL to start with the right thing
+    yourself:** `https://github.com/` or `https://gitlab.com/`
 
-    If you don't want VS Code to be connected to your GitHub account,
+    If you don't want VS Code to be connected to your GitHub or GitLab account,
     set up and use the SSH method instead.
   ::::
 
   ::::{group-tab} RStudio
     See our [installation instructions](https://coderefinery.github.io/installation/ssh/)
-    for how to run the GitHub configuration directly in RStudio using commands 
-    in the R package `usethis` and how to test that everything worked. These 
-    instructions use **HTTPS** for authentication.
+    for how to configure SSH or HTTPS authentication. In RStudio, these steps
+    can be run in the Terminal tab of the console panel.
 
     After the configuration, you should **select HTTPS as the clone URL from
-    GitHub, or translate the URL to start with the right thing
-    yourself:** `https://github.com/`
+    GitHub or GitLab, or translate the URL to start with the right thing
+    yourself:** `https://github.com/` or `https://gitlab.com/`
 
     To set your default branch name in Git to `main` in RStudio, run
 

content/merging.md

@@ -6,8 +6,8 @@ means that we have to somehow combine the changes later. In this part we will
 practice this: {term}`merging`.
 
 :::{objectives}
-- Understand that on GitHub merging is done through a {term}`pull request`. Think of it as a **change proposal**.
-- Create and merge a pull request within your own repository.
+- Understand that on GitHub merging is done through a {term}`pull request`. The equivalent on GitLab is called a {term}`merge request`. Think of it as a **change proposal**.
+- Create and merge a pull/merge request within your own repository.
 - Understand (and optionally) do the same across repositories, to contribute to
   the {term}`upstream` public repository.
 :::
@@ -97,6 +97,18 @@ We provide basic hints. You should refer to the solution as needed.
 :::
 ::::
 
+::::{group-tab} GitLab
+:::{exercise} Exercise: Merging branches with merge requests
+We assume that you have created a new branch with a recipe.
+
+1. Navigate to your branch.
+2. Click "Create merge request" in the upper right in the branch view.
+3. Provide a title and a description for the merge request. Make sure to merge with your own repository: click "Change branches", choose your own fork as the target project, and choose its `main` branch as the target branch.
+4. Create the merge request by clicking "Create merge request".
+5. Merge the merge request.
+6. Find out which branches are merged and thus safe to delete.
+::::
+
 ::::{group-tab} Local (VS Code, Command line, RStudio)
 
 When working locally, it's easier to merge branches: we can just do
@@ -149,6 +161,15 @@ On GitHub make sure you are on the branch you want to merge **from**:
    :::
 ::::
 
+::::{group-tab} GitLab
+On GitLab make sure you are on the branch you want to merge **from**:
+   :::{figure} img/gitlab/merging-navigate-branch-annotated.png
+   :alt: Screenshot on Gitlab where we navigate to the branch we wish to merge.
+   :width: 80%
+   :class: with-border
+   :::
+::::
+
 ::::{group-tab} VS Code
 Remember, you need to switch to the `main` branch, the branch we want to merge **to**.
 This is different from the GitHub path.
@@ -186,6 +207,14 @@ branches together.  We start the process of making one.
    :::
 ::::
 
+::::{group-tab} GitLab
+   :::{figure} img/gitlab/merging-open-merge-request-annotated.png
+   :alt: Screenshot on GitLab where we get to the merge request process.
+   :width: 80%
+   :class: with-border
+   :::
+::::
+
 ::::{group-tab} VS Code
 It is possible to open pull requests from the editor, but 
 we don't cover that here.
@@ -233,6 +262,27 @@ Things to check:
    :::
 ::::
 
+::::{group-tab} GitLab
+Things to check:
+- Target project: this should be your own
+- Title: make it descriptive
+- Description: make it informative
+- Scroll down to see commits: are these the ones you want to merge?
+- Scroll down to see the changes: are these the ones you want to merge?
+
+   :::{figure} img/gitlab/merging-change-branches-annotated.png
+   :alt: Screenshot on GitLab where we change branches.
+   :width: 80%
+   :class: with-border
+   :::
+
+   :::{figure} img/gitlab/merging-choose-target-branch-annotated.png
+   :alt: Screenshot on GitLab where we change target branch.
+   :width: 80%
+   :class: with-border
+   :::
+::::
+
 ::::{group-tab} VS Code
 If you are working locally, continue to step 5.
 ::::
@@ -248,10 +298,10 @@ If you are working locally, continue to step 5.
 :::::
 
 
-### (4) Create the pull request
+### (4) Create the pull/merge request
 
-We actually create the pull request.  Don't forget to navigate to the Network
-view after opening the pull request.  Note that the changes proposed in the
+We actually create the pull/merge request.  Don't forget to navigate to the Network
+view after opening the pull/merge request.  Note that the changes proposed in the
 pull request are not yet merged.
 
 :::::{tabs}
@@ -264,6 +314,10 @@ when collaborating with others. It allows you to open a pull request that is
 not ready to be merged yet, but you want to show it to others and get feedback.
 ::::
 
+::::{group-tab} GitLab
+Click on the black button "Create merge request". Below the title of the merge request you can choose "Mark as draft". This will be useful when collaborating with others. It allows you to open a merge request that is not ready to be merged yet, but you want to show it to others and get feedback.
+::::
+
 ::::{group-tab} VS Code
 It is possible to create pull requests from the editor, but 
 we don't cover that here.
@@ -301,6 +355,10 @@ After merging, verify the network view. Also navigate then to your "main"
 branch and check that your new recipe is there.
 ::::
 
+::::{group-tab} GitLab
+Review the merge request (commits and changes) and click "Merge". When merging, you can choose to delete the source branch at the same time.
+::::
+
 ::::{group-tab} VS Code
 Just like with the command line, when we merge we modify our *current* branch.  Verify you are on the `main` branch.
 
@@ -373,6 +431,16 @@ In the overview we can see that it has been merged and we can delete it:
    :::
 ::::
 
+::::{group-tab} GitLab
+One way to delete the branch is to check off "delete source branch" before merging. If you forgot to do so, you can delete the branch afterwards. Click on "branches" and find the branch that you want to delete. Click on the three dots to the right and choose "Delete branch".
+   :::{figure} img/gitlab/merging-delete-source-branch-annotated.png
+   :alt: Screenshot on Gitlab where we delete branch.
+   :width: 80%
+   :class: with-border
+   :::
+::::
+
+
 ::::{group-tab} VS Code
 From the Source Control sidebar → the three dots (as before) → Branch → Delete Branch.  Select the branch name to delete.
 ::::
@@ -425,6 +493,12 @@ merge the pull request.  We can then together review and browse the pull
 request.
 ::::
 
+::::{group-tab} GitLab
+Now you know how to create branches and open a merge request. Try to open a merge request with a new change but this time set the target project to the upstream repository. This means that you send a merge request across repositories: from your own fork to the original repository.
+
+Another thing that is different is that you might not have permission to merge the merge request. This means that someone with permission needs to review and approve your merge request.
+::::
+
 ::::{group-tab} VS Code
 Not described. We will return to this in the [collaborative Git
 lesson](https://coderefinery.github.io/git-collaborative/).
@@ -470,7 +544,7 @@ How to create a conflict (please try this in your own time *and just watch now*)
 - Now try to merge the new branch to `main`. You will get a conflict.
 
 How to resolve conflicts:
-- On GitHub, you can resolve conflicts by clicking on the "Resolve conflicts"
+- On GitHub and GitLab, you can resolve conflicts by clicking on the "Resolve conflicts"
   button. This will open a text editor where you can choose which changes to
   keep.
   Make sure to remove the conflict markers.

content/reference.md

@@ -114,6 +114,9 @@ merging
    Bringing changes from one branch into another, either as a noun or
    verb.
 
+merge request
+   A GitLab concept equivalent to {term}`pull request` on GitHub.
+
 VS Code
    A text editor and development environment by Microsoft.  It's quite
    popular, partly because it is powerful and easy to use.  [VS

content/sharing.md

@@ -35,13 +35,17 @@ From a bunch of files to a local repository which we then share on GitHub.
 2. Turn this new directory into a Git repository.
 3. Share this repository on GitHub (or GitLab, since it really works the same).
 
-We offer **three different paths** of how to do this exercise.
+We offer **five different paths** of how to do this exercise.
 * Via **GitHub web interface**: easy and can be a good starting point if you are completely
   new to Git.
+* Via **GitLab web interface**: similar to the GitHub path; create a blank
+  project, initialize it with a README file, and upload your project files.
 * **VS Code** is quite easy, since VS Code can offer to create the
   GitHub repositories for you.
 * **Command line**: you need to create the
   repository on GitHub and link it yourself.
+* **RStudio**: initialize Git for your project, connect it to an empty
+  repository on GitHub or GitLab, and use RStudio's Push and Pull buttons.
 
 ::::{tabs}
 
@@ -80,6 +84,33 @@ Click on the "+" symbol and then on "Upload files".
 ```
 :::
 
+:::{group-tab} GitLab
+**Create a repository on GitLab**
+First log in to GitLab, then follow the screenshots and descriptions below.
+```{figure} img/gitlab/sharing-projects-annotated.png
+:alt: Screenshot on GitLab where we start creating a new project.
+:width: 100%
+:class: with-border
+```
+After clicking "Create project", click "Create blank project".
+
+```{figure} img/gitlab/sharing-create-project-annotated.png
+:alt: Screenshot on GitLab where we create a new project.
+:width: 100%
+:class: with-border
+```
+*Choose a project name, add your username under "project URL", choose "Public", and add a README file. Finally "Create project".*
+
+**Upload your files**
+Now that the project is created, you can upload your files:
+```{figure} img/gitlab/sharing-upload-file-annotated.png
+:alt: Screenshot on GitLab where we upload files.
+:width: 100%
+:class: with-border
+```
+:::
+
+
 :::{group-tab} VS Code
 In VS Code it only takes few clicks.