Improve GitLab instructions (#136)

swiss-ai-center · Aug 21, 2023 · f2b52d0 · f2b52d0
1 parent 4d2ba88
commit f2b52d0
Show file tree

Hide file tree

Showing 30 changed files with 636 additions and 368 deletions.
diff --git a/docs/assets/images/cml_report1_dark.png → ...ssets/images/github_cml_report_1_dark.png b/docs/assets/images/cml_report1_dark.png → ...ssets/images/github_cml_report_1_dark.png
diff --git a/docs/assets/images/cml_report1_light.png → ...sets/images/github_cml_report_1_light.png b/docs/assets/images/cml_report1_light.png → ...sets/images/github_cml_report_1_light.png
diff --git a/docs/assets/images/cml_report2_dark.png → ...ssets/images/github_cml_report_2_dark.png b/docs/assets/images/cml_report2_dark.png → ...ssets/images/github_cml_report_2_dark.png
diff --git a/docs/assets/images/cml_report2_light.png → ...sets/images/github_cml_report_2_light.png b/docs/assets/images/cml_report2_light.png → ...sets/images/github_cml_report_2_light.png
diff --git a/docs/assets/images/gitlab_cml_report_1_dark.png b/docs/assets/images/gitlab_cml_report_1_dark.png
diff --git a/docs/assets/images/gitlab_cml_report_1_light.png b/docs/assets/images/gitlab_cml_report_1_light.png
diff --git a/docs/assets/images/gitlab_cml_report_2_dark.png b/docs/assets/images/gitlab_cml_report_2_dark.png
diff --git a/docs/assets/images/gitlab_cml_report_2_light.png b/docs/assets/images/gitlab_cml_report_2_light.png
diff --git a/docs/clean-up.md b/docs/clean-up.md
@@ -33,6 +33,20 @@ provider.
     gcloud container clusters delete --zone $GCP_CLUSTER_ZONE $GCP_CLUSTER_NAME
     ```
 
+    Press ++Y++ to confirm the deletion.
+
+    **Delete the Google Artifact Registry**
+
+    To delete the Google Artifact Registry used to store the Docker images you
+    created you can execute the following command:
+
+    ```sh title="Execute the following command(s) in a terminal"
+    # Delete the Kubernetes cluster
+    gcloud artifacts repositories delete --location $GCP_REPOSITORY_LOCATION $GCP_REPOSITORY_NAME
+    ```
+
+    Press ++Y++ to confirm the deletion.
+
     **Delete the Google Storage bucket**
 
     !!! warning
@@ -49,14 +63,7 @@ provider.
     gcloud storage rm --recursive gs://$GCP_BUCKET_NAME
     ```
 
-    Alternatively, you can delete the bucket from the Google Cloud Console:
-
-    1. Go to the
-       [Google Cloud Storage Console](https://console.cloud.google.com/storage){:target="\_blank"}.
-    2. Make sure you selected the correct project.
-    3. Select the bucket you want to delete from the bucket list.
-    4. Click on **Delete** at the top of the page.
-    5. Follow the instructions to delete the bucket.
+    Press ++Y++ to confirm the deletion.
 
     **Delete the Service Account**
 
@@ -67,23 +74,17 @@ provider.
     gcloud iam service-accounts delete dvc-service-account@${GCP_PROJECT_ID}.iam.gserviceaccount.com
     ```
 
-    Alternatively, you can delete the service account from the Google Cloud Console:
-
-    1. Go to the
-       [Google Cloud IAM Console](https://console.cloud.google.com/iam-admin/serviceaccounts){:target="\_blank"}.
-    2. Make sure you selected the correct project.
-    3. Select the service account you want to delete from the service account list.
-    4. Click on **Delete** at the top of the page.
-    5. Follow the instructions to delete the service account.
+    Press ++Y++ to confirm the deletion.
 
-    **Delete the local Service Account key**
+    **Delete the local Service Account keys**
 
-    You can run the following command to delete the service account key you created
+    You can run the following command to delete the service account keys you created
     locally:
 
     ```sh title="Execute the following command(s) in a terminal"
     # Delete the local Service Account key
     rm ~/.config/gcloud/dvc-google-service-account-key.json
+    rm ~/.config/gcloud/mlem-google-service-account-key.json
     ```
 
     **Delete the Google Cloud project**
@@ -98,7 +99,7 @@ provider.
 
     **Close the Billing Account**
 
-    To remove the project from the Billing Acocunt:
+    To remove the project from the Billing Account:
 
     1. Go to the
        [Google Cloud Billing Console](https://console.cloud.google.com/billing){:target="\_blank"}.
@@ -220,10 +221,11 @@ Here is a checklist of all the resources and environments you created.
     You can click on the list items to mark them as completed if needed.
 
 - [ ] The cloud provider Kubernetes cluster
+- [ ] The cloud provider container registry
 - [ ] The cloud provider S3 bucket
 - [ ] The cloud provider credentials
 - [ ] The cloud provider project
-- [ ] The GitHub or GitLab Personal Access Token
+- [ ] The GitHub or GitLab Personal Access Tokens
 - [ ] The GitHub or GitLab repository
 - [ ] The projects directories
     - [ ] The `a-guide-to-mlops-jupyter-notebook` directory

diff --git a/...-model-evaluation/chapter-1-run-a-simple-ml-experiment-with-jupyter-notebook.md b/...-model-evaluation/chapter-1-run-a-simple-ml-experiment-with-jupyter-notebook.md
@@ -158,11 +158,12 @@ Launch the notebook.
 jupyter-lab notebook.ipynb
 ```
 
-A browser window should open with the Jupyter Notebook.
+A browser window should open with the Jupyter Notebook at
+<http://localhost:8888/lab/tree/notebook.ipynb>.
 
-You may notice all the previous outputs from the notebook are still present.
-This is because the notebook was not cleared before being shared with you. This
-can be useful to see the results of previous runs.
+You may notice all the previous outputs from the notebook might still be
+present. This is because the notebook was not cleared before being shared with
+you. This can be useful to see the results of previous runs.
 
 In most cases, however, it can also be a source of confusion and clutter. This
 is one of the limitations of the Jupyter Notebook, which make them not always

diff --git a/...l-evaluation/chapter-2-adapt-and-move-the-jupyter-notebook-to-python-scripts.md b/...l-evaluation/chapter-2-adapt-and-move-the-jupyter-notebook-to-python-scripts.md
@@ -1,14 +1,5 @@
 # Chapter 2: Adapt and move the Jupyter Notebook to Python scripts
 
-??? info "You want to take over from this chapter? Collapse this section and follow the instructions below."
-
-    !!! warning
-
-        It might be easier to start from the previous chapter(s). Only follow this
-        section if you are comfortable with the content of the previous chapter(s).
-
-    Work in progress.
-
 ## Introduction
 
 Jupyter Notebooks provide an interactive environment where code can be executed

diff --git a/...ing-and-model-evaluation/chapter-3-initialize-git-and-dvc-for-local-training.md b/...ing-and-model-evaluation/chapter-3-initialize-git-and-dvc-for-local-training.md
@@ -1,14 +1,5 @@
 # Chapter 3: Initialize Git and DVC for local training
 
-??? info "You want to take over from this chapter? Collapse this section and follow the instructions below."
-
-    !!! warning
-
-        It might be easier to start from the previous chapter(s). Only follow this
-        section if you are comfortable with the content of the previous chapter(s).
-
-    Work in progress.
-
 ## Introduction
 
 Now that you have a good understanding of the experiment, it's time to
@@ -404,7 +395,8 @@ This chapter is done, you can check the summary.
 
 ## Summary
 
-Congrats! You now have a dataset that can be used and shared among the team.
+Congratulations! You now have a dataset that can be used and shared among the
+team.
 
 In this chapter, you have successfully:
 

diff --git a/...training-and-model-evaluation/chapter-4-reproduce-the-ml-experiment-with-dvc.md b/...training-and-model-evaluation/chapter-4-reproduce-the-ml-experiment-with-dvc.md
@@ -1,14 +1,5 @@
 # Chapter 4: Reproduce the ML experiment with DVC
 
-??? info "You want to take over from this chapter? Collapse this section and follow the instructions below."
-
-    !!! warning
-
-        It might be easier to start from the previous chapter(s). Only follow this
-        section if you are comfortable with the content of the previous chapter(s).
-
-    Work in progress.
-
 ## Introduction
 
 A key component of [:simple-dvc: DVC](../tools.md) is the concept of "stages".
@@ -26,9 +17,9 @@ In this chapter, you will learn how to:
 
 1. Remove custom rules from the `.gitignore` file
 2. Set up DVC pipeline stages:
-    - `prepare`
-    - `train`
-    - `evaluate`
+    - Prepare
+    - Train
+    - Evaluate
 3. Visualize the pipeline
 4. Execute the pipeline
 5. Push the changes to DVC and Git
@@ -379,15 +370,16 @@ This chapter is done, you can check the summary.
 
 ## Summary
 
-Congrats! You have defined a pipeline and know how to reproduce your experiment.
+Congratulations! You have defined a pipeline and know how to reproduce your
+experiment.
 
 In this chapter, you have successfully:
 
 1. Removed custom rules from the `.gitignore` file
 2. Set up three DVC pipeline stages
-    - `prepare`
-    - `train`
-    - `evaluate`
+    - Prepare
+    - Train
+    - Evaluate
 3. Visualized the pipeline
 4. Executed the pipeline
 5. Committed the changes

diff --git a/...local-training-and-model-evaluation/chapter-5-track-model-evolution-with-dvc.md b/...local-training-and-model-evaluation/chapter-5-track-model-evolution-with-dvc.md
@@ -1,14 +1,5 @@
 # Chapter 5: Track model evolution with DVC
 
-??? info "You want to take over from this chapter? Collapse this section and follow the instructions below."
-
-    !!! warning
-
-        It might be easier to start from the previous chapter(s). Only follow this
-        section if you are comfortable with the content of the previous chapter(s).
-
-    Work in progress.
-
 ## Introduction
 
 In the previous chapter, you did set up a [:simple-dvc: DVC](../tools.md)
@@ -74,8 +65,8 @@ index 5bb698e..6a6ff45 100644
    output_classes: 11
 ```
 
-Here, you simply changed the `epochs` parameter of the `train` stage, which
-should slightly affect the model's performance.
+Here, you simply changed the `epochs` parameter of the Train stage, which should
+slightly affect the model's performance.
 
 ### Reproduce the experiment
 
@@ -256,7 +247,7 @@ This chapter is done, you can check the summary.
 
 ## Summary
 
-Congrats! You now have a simple way to compare the two iterations of your
+Congratulations! You now have a simple way to compare the two iterations of your
 experiment.
 
 In this chapter, you have successfully:

diff --git a/...-model-to-the-cloud/chapter-10-work-efficiently-and-collaboratively-with-git.md b/...-model-to-the-cloud/chapter-10-work-efficiently-and-collaboratively-with-git.md
@@ -1,14 +1,5 @@
 # Chapter 10: Work efficiently and collaboratively with Git
 
-??? info "You want to take over from this chapter? Collapse this section and follow the instructions below."
-
-    !!! warning
-
-        It might be easier to start from the previous chapter(s). Only follow this
-        section if you are comfortable with the content of the previous chapter(s).
-
-    Work in progress.
-
 ## Introduction
 
 The objective of this chapter is to work effectively and collaboratively on the
@@ -233,9 +224,6 @@ repository.
 Check the changes with Git to ensure all wanted files are here.
 
 ```sh title="Execute the following command(s) in a terminal"
-# Upload the experiment data and cache to the remote bucket
-dvc push
-
 # Add all the files
 git add .
 
@@ -255,7 +243,12 @@ Changes to be committed:
         modified:   params.yaml
 ```
 
+Push the changes to the remote repository.
+
 ```sh title="Execute the following command(s) in a terminal"
+# Upload the experiment data and cache to the remote bucket
+dvc push
+
 # Commit the changes
 git commit -m "I made some changes to the model"
 
@@ -313,23 +306,35 @@ git push
     evaluation data that was pulled from DVC, it can uses it to display all the
     plots.
 
+    <div style="display: flex" markdown>
+        <figure markdown>
+            ![Plots Diff 1 Light](../assets/images/github_cml_report_1_light.png#only-light){ loading=lazy }
+        </figure> <figure markdown>
+            ![Plots Diff 1 Dark](../assets/images/github_cml_report_1_dark.png#only-dark){ loading=lazy }
+        </figure> <figure markdown>
+            ![Plots Diff 2 Light](../assets/images/github_cml_report_2_light.png#only-light){ loading=lazy }
+        </figure> <figure markdown>
+            ![Plots Diff 2 Dark](../assets/images/github_cml_report_2_dark.png#only-dark){ loading=lazy }
+        </figure>
+    </div>
+
 === ":simple-gitlab: GitLab"
 
     When the CI/CD pipeline completes, a new comment is added to your merge request.
     Check the merge request and examine the report made by CML. As it uses the
     evaluation data that was pulled DVC, it can uses it to display all the plots.
 
-<!-- Note: Do not indent this code, this is the only way it displays the images
-     properly -->
-<div style="display: flex" markdown> <figure markdown>
-![Plots Diff 1 Light](../assets/images/cml_report1_light.png#only-light){ loading=lazy }
-</figure> <figure markdown>
-![Plots Diff 1 Dark](../assets/images/cml_report1_dark.png#only-dark){ loading=lazy }
-</figure> <figure markdown>
-![Plots Diff 2 Light](../assets/images/cml_report2_light.png#only-light){ loading=lazy }
-</figure> <figure markdown>
-![Plots Diff 2 Dark](../assets/images/cml_report2_dark.png#only-dark){ loading=lazy }
-</figure> </div>
+    <div style="display: flex" markdown>
+        <figure markdown>
+            ![Plots Diff 1 Light](../assets/images/gitlab_cml_report_1_light.png#only-light){ loading=lazy }
+        </figure> <figure markdown>
+            ![Plots Diff 1 Dark](../assets/images/gitlab_cml_report_1_dark.png#only-dark){ loading=lazy }
+        </figure> <figure markdown>
+            ![Plots Diff 2 Light](../assets/images/gitlab_cml_report_2_light.png#only-light){ loading=lazy }
+        </figure> <figure markdown>
+            ![Plots Diff 2 Dark](../assets/images/gitlab_cml_report_2_dark.png#only-dark){ loading=lazy }
+        </figure>
+    </div>
 
 ### Merge the pull request/merge request
 
@@ -346,7 +351,7 @@ git push
     repository. If you ever need to go back to this branch, you can always restore
     the branch from this menu.
 
-    Congrats! You can now iterate on your model while keeping a trace of the
+    Congratulations! You can now iterate on your model while keeping a trace of the
     improvements made to it. You can visualize and discuss the changes made to a
     model before merging them into the codebase.
 
@@ -360,7 +365,7 @@ git push
 
     The associated issue will be automatically closed as well.
 
-    Congrats! You can now iterate on your model while keeping a trace of the
+    Congratulations! You can now iterate on your model while keeping a trace of the
     improvements made to it. You can visualize and discuss the changes made to a
     model before merging them into the codebase.
 

diff --git a/...ve-the-model-to-the-cloud/chapter-6-move-the-ml-experiment-code-to-the-cloud.md b/...ve-the-model-to-the-cloud/chapter-6-move-the-ml-experiment-code-to-the-cloud.md
@@ -1,14 +1,5 @@
 # Chapter 6: Move the ML experiment code to the cloud
 
-??? info "You want to take over from this chapter? Collapse this section and follow the instructions below."
-
-    !!! warning
-
-        It might be easier to start from the previous chapter(s). Only follow this
-        section if you are comfortable with the content of the previous chapter(s).
-
-    Work in progress.
-
 ## Introduction
 
 Now that you have configured [:simple-dvc: DVC](../tools.md) and can reproduce
@@ -80,24 +71,24 @@ Create a Git repository on your preferred service to collaborate with peers.
 
 === ":simple-github: GitHub"
 
-    Create a new GitHub repository for this chapter by accessing
-    <https://github.com/new>.
-
-    !!! warning
+    !!! danger "Important"
 
         Configure the repository as you wish but **do not** check the boxex
         _"Add a README file"_, _"Add .gitignore"_ nor _"Choose a license"_.
 
-=== ":simple-gitlab: GitLab"
+    Create a new GitHub repository for this chapter by accessing
+    <https://github.com/new>.
 
-    Create a new GitLab blank project for this chapter by accessing
-    <https://gitlab.com/projects/new>.
+=== ":simple-gitlab: GitLab"
 
-    !!! warning
+    !!! danger "Important"
 
         Configure the repository as you wish but **do not** check the box
         _"Initialize repository with a README"_.
 
+    Create a new GitLab blank project for this chapter by accessing
+    <https://gitlab.com/projects/new>.
+
 ## Configure Git for the remote branch
 
 Add the remote origin to your repository. Replace `<your git repository url>`
@@ -131,7 +122,8 @@ points.
 
 ## Summary
 
-Congrats! You now have a codebase that can be used and shared among the team.
+Congratulations! You now have a codebase that can be used and shared among the
+team.
 
 In this chapter, you have successfully: