Update documentation and CI/CD configurations

- Revised the Contributor Code of Conduct for clarity and inclusivity.
- Added new episodes (06-catservices.md, 07-final-run.md) to the curriculum, detailing CAT services and final run integration.
- Updated existing episodes (03-gitlabci-setenv.md, 04-gitlabci-run-analysis.md, 05-gitlabci-vomsproxy.md) with improved instructions and examples.
- Removed the outdated episode (07-building-image.md) related to container image building.
- Enhanced links.md with additional references for CMS analysis and GitLab CI/CD.
- Adjusted config.yaml to include new episodes in the lesson structure.

Author: alefisico

CODE_OF_CONDUCT.md

@@ -10,7 +10,7 @@ We follow the [CERN Code of Conduct](https://hr-dep.web.cern.ch/content/code-of-
 
 We commit to helping our community adhere to this code of conduct and speak up when we see possible violations of it. We strive to treat those outside of CMS as we would members of our own community. In the event that the letter or the spirit of this code has been violated, appropriate action will be taken, up to and including procedures specified in Annex A3.2 of the CMS Constitution.
 
-If you want to know more about the *CMS Diversity & Inclusion Office* follow the [link](https://twiki.cern.ch/twiki/bin/view/CMSPublic/CMSDiversityOffice) and check out the [booklet](https://heyzine.com/flip-book/00f6546b1c.html).
+You can also learn more about the [CMS Diversity & Inclusion Office](https://twiki.cern.ch/twiki/bin/view/CMSPublic/CMSDiversityOffice) and its activities. Dont forget to [check out the booklet](https://heyzine.com/flip-book/00f6546b1c.html).
 
 ---
 

config.yaml

@@ -70,6 +70,9 @@ episodes:
 - 03-gitlabci-setenv.md
 - 04-gitlabci-run-analysis.md
 - 05-gitlabci-vomsproxy.md
+- 06-catservices.md
+- 07-final-run.md
+# - A-extra-building-image.md
 
 # Information for Learners
 learners: 

episodes/03-gitlabci-setenv.md

@@ -26,7 +26,7 @@ If you skipped the previous lessons, ensure you have:
 
 - A GitLab repository at CERN GitLab (named `cmsdas-gitlab-cms`).
 - The repository cloned to your local machine with an empty `.gitlab-ci.yml` file.
-- The example [analysis code](../files/ZPeakAnalysis.zip) downloaded and added to your repository.
+- The example [analysis code](files/ZPeakAnalysis.zip) downloaded and added to your repository.
 
 :::::
 

episodes/04-gitlabci-run-analysis.md

@@ -15,7 +15,7 @@ exercises: 10
 :::::::: objectives
 
 - Run a CMSSW analysis job in GitLab CI using a CVMFS-enabled runner.
-- Configure `.gitlab-ci.yml` to reuse a built CMSSW release via artifacts instead of rebuilding each time.
+- Configure `.gitlab-ci.yml` to reuse a built CMSSW release via artifacts instead of rebuilding each time, and handle write-protection in downstream jobs.
 - Validate the analysis output (ROOT file and event counts) within the CI pipeline.
 
 :::::::: 
@@ -135,8 +135,13 @@ cmssw_run:
   script:
     - set +u && source ${CMS_PATH}/cmsset_default.sh; set -u
     - export SCRAM_ARCH=${SCRAM_ARCH}
-    - cd ${CMSSW_RELEASE}/src
+    - mkdir -p run
+    - cp -r ${CMSSW_RELEASE} run/
+    - chmod -R +w run/${CMSSW_RELEASE}/
+    - cd run/${CMSSW_RELEASE}/src
     - cmsenv
+    - mkdir -p AnalysisCode
+    - cp -r $CI_PROJECT_DIR/ZPeakAnalysis AnalysisCode/
     - cd AnalysisCode/ZPeakAnalysis/
     - cmsRun test/MyZPeak_cfg.py
     - ls -l myZPeak.root
@@ -161,14 +166,81 @@ check_events:
   script:
     - set +u && source ${CMS_PATH}/cmsset_default.sh; set -u
     - export SCRAM_ARCH=${SCRAM_ARCH}
-    - cd ${CMSSW_RELEASE}/src
+    - mkdir -p run
+    - cp -r ${CMSSW_RELEASE} run/
+    - chmod -R +w run/${CMSSW_RELEASE}/
+    - cd run/${CMSSW_RELEASE}/src
     - cmsenv
+    - mkdir -p AnalysisCode
+    - cp -r $CI_PROJECT_DIR/ZPeakAnalysis AnalysisCode/
     - cd AnalysisCode/ZPeakAnalysis/
     - python3 test/check_number_events.py --input ${CMSSW_RELEASE}/src/AnalysisCode/ZPeakAnalysis/myZPeak.root
     - python3 test/check_cutflows.py number_of_events.txt test/number_of_expected_events.txt
 ```
 
-If you are satisfied with your pipeline, commit and push the changes. Check the pipeline logs for errors and verify that output files are produced as expected.
+For the compiled code to be available in subsequent steps, the artifacts must be explicitly defined. In the `cmssw_compile` job, we specify:
+
+```yaml
+artifacts:
+  untracked: true
+  expire_in: 1 hour
+  paths:
+    - ${CMSSW_RELEASE}
+```
+
+**Key options:**
+
+- **`untracked: true`:** Includes files not tracked by git (ignores `.gitignore`), ensuring the full CMSSW build area is captured.
+- **`expire_in`:** Specifies how long artifacts are kept before automatic deletion. Use `1 hour` for testing or `1 week` for longer workflows.
+- **`paths`:** Lists directories/files to preserve. Here, `${CMSSW_RELEASE}` captures the entire CMSSW work area.
+
+:::::::: callout
+
+### Artifacts Are Write-Protected
+
+Artifacts are write-protected by default. You cannot modify files directly in the artifact directory in downstream jobs.
+
+::::::::
+
+To work around this, copy the artifact to a new directory and add write permissions:
+
+```yaml
+script:
+  - set +u && source ${CMS_PATH}/cmsset_default.sh; set -u
+  - export SCRAM_ARCH=${SCRAM_ARCH}
+  - mkdir -p run
+  - cp -r ${CMSSW_RELEASE} run/
+  - chmod -R +w run/${CMSSW_RELEASE}/
+  - cd run/${CMSSW_RELEASE}/src
+  - cmsenv
+  - mkdir -p AnalysisCode
+  - cp -r $CI_PROJECT_DIR/ZPeakAnalysis AnalysisCode/
+  - cd AnalysisCode/ZPeakAnalysis/
+  - cmsRun test/MyZPeak_cfg.py
+```
+
+This ensures `cmssw_run` and `check_events` can reuse the built CMSSW area without rebuilding, while still being able to write output files.
+
+### Using `needs` vs `dependencies`
+
+In the pipeline above, we use the `needs` keyword to define job dependencies:
+
+```yaml
+cmssw_run:
+  needs:
+    - cmssw_compile
+  stage: run
+  # ...
+```
+
+**Differences between `needs` and `dependencies`:**
+
+| Keyword | Behavior |
+|---------|----------|
+| [`needs`][gitlab-need] | Job starts **immediately** when the needed job completes, regardless of stage. Enables parallelism. |
+| [`dependencies`][gitlab-dependencies] | Job starts only when **all jobs in the prior stage** complete. Strictly follows stage order. |
+
+**Best practice:** Use `needs` for faster pipelines—it allows jobs to start as soon as their dependencies are met, rather than waiting for an entire stage to finish.
 
 ::::::: discussion
 #### How does this updated pipeline improve efficiency?
@@ -210,7 +282,11 @@ If yes, you dont need the rest of the lessons. If they are failing, continue wit
 :::::: keypoints
 
 - GitLab CI runs on remote runners; every dependency and setup step must be in `.gitlab-ci.yml`.
+- Use CVMFS-enabled Kubernetes runners (`k8s-cvmfs`); the `image:` keyword is honored only there.
 - Split the pipeline into stages and pass the built CMSSW area via artifacts to avoid rebuilding in each job.
 - Validate outputs in CI (e.g., `myZPeak.root`, event counts) to catch issues early; inspect job logs for failures.
+- Artifacts are write-protected by default; downstream jobs must copy them to a writable directory using `mkdir`, `cp -r`, and `chmod -R +w`.
+- Define artifacts with `untracked: true` to capture build outputs, and set `expire_in` to control automatic cleanup (e.g., `1 hour` for testing, `1 week` for production).
+- Use the `needs` keyword for faster pipelines—jobs start immediately when dependencies complete, rather than waiting for entire stages to finish. `dependencies` is an alternative that strictly respects stage order.
 
 ::::::

episodes/05-gitlabci-vomsproxy.md

@@ -198,13 +198,13 @@ For each variable:
 
 The **Settings > CI/CD > Variables** section should look like this:
 
-![CI/CD Variables section with grid secrets added](fig/variables_gitlab.png)
+![CI/CD Variables section with grid secrets added](fig/variables_gitlab.png){alt='CI/CD Variables section with grid secrets added'}
 
 ### Protect Your Main Branch
 
 To reduce the risk of leaking passwords and certificates to others, go to **Settings > Repository > Protected Branches** and protect your `master` or `main` branch. This prevents collaborators from pushing directly and accidentally exposing secrets in job logs.
 
-![Protecting branches to prevent password leaks](fig/protected_branches.png)
+![Protecting branches to prevent password leaks](fig/protected_branches.png){alt='Protecting branches to prevent password leaks'}
 
 With the **Protected** option enabled for variables, they are only available to those protected branches (though Maintainers can still push to them).