Merge pull request #23 from t4d-gmbh/13-review-part-2

13 review part 2

source/content/contributing/step_by_step.md

@@ -4,7 +4,7 @@
 {% else %} 
    - Browse existing Issues - {octicon}`issue-opened;0.8em` open and {octicon}`issue-closed;0.8em` closed ones - to see if the same or a similar Issue was already created.
    - If your Issue exists already, check for related Merge/Pull Requests and if they implement what you had in mind.
-     If not, scip the next step (i.e. don't create a new {octicon}`issue-opened;0.8em` Issue) and simply proceed with step 3. **Read Documentation**.
+     If not, skip the next step (i.e. don't create a new {octicon}`issue-opened;0.8em` Issue) and simply proceed with step 3. **Read Documentation**.
 {% endif %}
 
 {% if page %}##### {% endif %}2. **Open an {octicon}`issue-opened;0.8em` Issues** 📝{% if slide %} Explain why some work needs to be done.
@@ -31,7 +31,7 @@
      For smaller changes you might directly work on the healthy reference (i.e. **`main`**) of the forked repository.
      Bigger changes should be implemented in a separate branch following the feature branch approach, for example.
    - Follow the project's coding style and guidelines.
-   - Make sure the branch you implement the changes in remains up to date with the target branch from to repository.
+   - Make sure the branch on which you implement the changes, remains up to date with the target branch from to repository.
    - Test and document your changes.
 {% endif %}
 
@@ -48,11 +48,11 @@
 {% else %}
    - Engage with project maintainers and other contributors during the review process.
    - Be open to feedback and make any necessary revisions.
-   - Respect the maintainers decisions and adaptations, if you are not happy with them you can alwasy keep your forked repository and maintain it on your own!
+   - Respect the maintainers decisions and adaptations, if you are not happy with them you can always keep your forked repository and maintain it on your own!
 {% endif %}
 
 {% if page %}#### {% endif %}8. 🌟 **Stay Engaged** 🌟{% if slide %}
 {% else %}
-   - Once the Merge/Pull Request is merged or closed, feel free to delete your fork of the repository again.
+   - Once the Merge/Pull Request is merged or closed, feel free to delete your fork of the repository. This avoids confusion about which repository is the most up-to-date.
    - Continue to contribute to the project by helping with other issues or discussions.
 {% endif %}

source/content/popular_remotes/github.md

@@ -1,6 +1,10 @@
-## GitHub
+## GitHub <i class="fab fa-github"></i>
 
-GitHub is a leading platform for hosting and managing code repositories, enabling collaboration, issue tracking, and CI/CD workflows. Founded in 2008 and acquired by Microsoft in 2018, it is known for its user-friendly interface and extensive community support.
+GitHub is a leading platform for hosting and managing code repositories, enabling collaboration, issue tracking, and CI/CD workflows. Founded in 2008 and acquired by Microsoft in 2018{% if page %}[^sn1]{% endif %}, it is known for its user-friendly interface and extensive community support.
+
+{% if page %}
+[^sn1]: Before the acquisition, GitHub was an open-source platform, and the acquisition raised concerns about the platform's future direction and lead to an exodus of users to other platforms like GitLab.
+{% endif %}
 
 **Pros:**
 - User-friendly interface

source/content/popular_remotes/gitlab.md

@@ -1,4 +1,4 @@
-## GitLab
+## GitLab <i class="fab fa-gitlab"></i>
 
 GitLab is a popular, open-source platform for hosting and managing code repositories, offering comprehensive DevOps features for collaboration, issue tracking, and CI/CD workflows. 
 Founded in 2011, GitLab is compared to GitHub fully open-source and provides a similar feature set that supports the entire software development lifecycle but has a stronger focus on self-hosted and on-premise installations.

source/content/popular_remotes/index.md

@@ -26,7 +26,7 @@
 ```
 <!-- ```{include} ./bitbucket.md
 ``` -->
-# Remote Services at the University
+# Remote Services at the University of Zurich
 ```{include} ./remote_services_at_uzh_imathGitLab.md
 ```
 ```{include} ./remote_services_at_uzh_uzhGitLab.md

source/content/popular_remotes/overview_popular_remotes.md

@@ -10,12 +10,12 @@ They allow multiple users to work on the same project simultaneously, track chan
 
 | **Remote Service** | **Founded** | **Acquired/Owned by** | **Popularity** | **Key Features** | **Costs** |
 |--------------------|-------------|-----------------------|----------------|------------------|-----------|
-| **GitHub** ![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)   | 2008        | Microsoft (2018)      | Widely used by open-source communities and enterprises.<br>Known for its user-friendly interface and extensive community support. | - **Repository hosting**<br>- **Pull requests**<br>- **Issues and bug tracking**<br>- **Wikis**<br>- GitHub Actions for CI/CD<br>- Project boards | Free for public repositories, paid plans for private repositories and additional features. |
-| **GitLab** ![GitLab Logo](https://about.gitlab.com/images/press/logo/png/gitlab-icon-rgb.png) | 2011        | -                     | Popular among developers and enterprises.<br>Known for its open-source nature and flexibility. | - **Repository hosting**<br>- **Merge requests**<br>- **Issues and bug tracking**<br>- **Wikis**<br>- **Integrated CI/CD**<br>- Web IDE<br>- Workspaces | Free tier, paid plans for additional features and support. |
+| **GitHub** <i class="fab fa-github" style="font-size:50px;"></i>   | 2008        | Microsoft (2018)      | Widely used by open-source communities and enterprises.<br>Known for its user-friendly interface and extensive community support. | - **Repository hosting**<br>- **Pull requests**<br>- **Issues and bug tracking**<br>- **Wikis**<br>- GitHub Actions for CI/CD<br>- Project boards | Free for public repositories, paid plans for private repositories and additional features. |
+| **GitLab** <i class="fab fa-gitlab" style="font-size:50px;"></i> | 2011        | -                     | Popular among developers and enterprises.<br>Known for its open-source nature and flexibility. | - **Repository hosting**<br>- **Merge requests**<br>- **Issues and bug tracking**<br>- **Wikis**<br>- **Integrated CI/CD**<br>- Web IDE<br>- Workspaces | Free tier, paid plans for additional features and support. |
 
   {% else %}
 
-| **Aspect** | **GitHub** | **GitLab** |
+| **Aspect** | **GitHub** <i class="fab fa-github"></i> | **GitLab** <i class="fab fa-gitlab"></i> |
 |------------|------------|------------|
 | <span style="font-size:14px;">**Repository Hosting**</span>  | <span style="font-size:14px;">Yes</span> | <span style="font-size:14px;">Yes</span> |
 | <span style="font-size:14px;">**Pull Requests/Merge Requests**</span> | <span style="font-size:14px;">Pull Requests</span> | <span style="font-size:14px;">Merge Requests</span> |

source/content/popular_remotes/remote_services_at_uzh_uzhGithub.md

@@ -1,8 +1,11 @@
 ## UZH GitHub
-UZH members can use their UZH email address to sign up for a GitHub account. This account can be used for both private and public repositories. GitHub offers free plans for public repositories and paid plans for private repositories and additional features. 
+UZH members can use their UZH email address to sign up for a GitHub account. 
+This account can be used for both private and public repositories. GitHub offers free plans for public repositories and paid plans for private repositories and additional features. 
 
-UZH has no official GitHub Enterprise license for the entire university. However, some departments or research groups may have their own licenses. Please check with your IT department or supervisor for more information.
+UZH has *no* official GitHub Enterprise license for the entire university. 
+However, some departments or research groups may have their own licenses. Please check with your IT department or supervisor for more information.
 
 # GitHub Education
-The UZH itself is accepted by GitHub as an educational
-institution. Any user with a UZH email address can get verfied as at [github.com/education](https://github.com/education) and get access to the GitHub Student Developer Pack. This pack includes free access to various tools and services for students and educators.
+The UZH itself is accepted by GitHub as an educational institution. 
+Any user with a UZH email address can get verfied as at [github.com/education](https://github.com/education) and get access to the GitHub Student Developer Pack. 
+This pack includes free access to various tools and services for students and educators.

source/content/project_management/feature_branch_reload/index.md

@@ -1,6 +1,6 @@
 ## Feature Branch Approach - _reloaded_
 {% if page %}
-Now that we know some of the [Collaboration Tools](./../../remote_service_features/collaboration_tools/index.md#collaboration-tools)  <i class="fab fa-git"></i> remotes services provide we can revise the [✨Feature✨ Branch Approach](https://t4d-gmbh.github.io/working-with-git/content/feature_branch/index.html) from our course [working-with-git](https://t4d-gmbh.github.io/working-with-git/).
+Now that we know some of the [Collaboration Tools](./../../remote_service_features/collaboration_tools/index.md#collaboration-tools)  <i class="fab fa-git"></i> remotes services provide, we can revise the [✨Feature✨ Branch Approach](https://t4d-gmbh.github.io/working-with-git/content/feature_branch/index.html) from our course [working-with-git](https://t4d-gmbh.github.io/working-with-git/).
 
 Let us quickly recall that a "Feature Branch" is a <i class="fab fa-git"></i> branch dedicated for the implementation of a distinct functionality, attribute, or similar and it should be intuitively clear that a collaborative context requires some form of documentation for the feature itself and ideally for the process of its implementation, as well.
 {% else %}

source/content/project_management/feature_branch_reload/workflow.md

@@ -7,12 +7,13 @@ Allows to perform steps **2** and **3** in a combined manner.
 {% if page %}##### {% endif %}1. **Create an Issue** 📝{% if slide %} Define and plan feature{% endif %}
 {% if page %}
 - **Identify the Feature**: Start by identifying the feature you want to develop.
-- **Check for similar Issues**: It is always a good practice check for existing Issues, no need to create duplicates if an identical or similar Issue already exists.
-- **Create an Issue**: Include details:
+- **Check for similar Issues**: It is always a good practice check for existing Issues; there's no need to create duplicates if an identical or similar Issue already exists.
+- **Formulate the Issue**: Include details:
   - Description of the feature
   - Acceptance criteria
   - Any relevant design mockups or specifications
   - Priority and estimated effort
+  - If it is a bug, include steps to reproduce and state the expected behavior
 {% endif %}
 
 {% if page %}##### {% endif %}2. **Create a Feature Branch** 🌿{% if slide %} Branch from healthy reference{% endif%}
@@ -37,9 +38,9 @@ Allows to perform steps **2** and **3** in a combined manner.
 {% if page %}##### {% endif %}3. **Create a Merge/Pull Request** 🔄{% if slide %} Push branch to remote and link to Issue (e.g. "Closes #123"){% endif %}
 {% if page %}
 - **Push the Branch**: Once the feature is complete and tested, push the feature branch to the remote repository.
-- **Open a Merge Request**: Create a merge request (MR) or pull request (PR) in your version control system (e.g., GitHub, GitLab, Bitbucket). In the MR/PR:
+- **Formulate a Merge/Pull Request**: Create a merge request (MR) or pull request (PR) on GitHub, GitLab, etc. In the MR/PR:
   - Reference the original issue (e.g., "Closes #123") to link the feature to the issue.
-  - Provide a description of the changes made and any relevant context.
+  - Provide a description of the changes that you made and any relevant context.
   - Specify any additional reviewers or stakeholders.
   :::{note}
   A common suggestion is to create a Merge/Pull Request **after having implemented** the feature (i.e. after [5. **Test the Feature**](#test-the-feature)).

source/content/project_management/git_plus_remote_tools.md

@@ -3,7 +3,7 @@
 {% if page %}
 With <i class="fab fa-git"></i> we posses a powerful tool to structure how we develop the content of a repository.
 Tools like Issues and Merge/Pull Request, provided by remote services, allow us to extensively document and track activities around any sort of plans, ideas, issues (not an Issue!), questions and suggestions.
-What we are still missing is to learn how events and actions in <i class="fab fa-git"></i> relate to events and actions within these remote tools, and vice-versa.
+What we are still missing is how events and actions in <i class="fab fa-git"></i> relate to events and actions within these remote tools, and vice-versa.
 
 As a start, let's simply clarify that:
 {% endif %}
@@ -13,10 +13,10 @@ Some remote services can trigger events and actions in <i class="fab fa-git"></i
 {% if page %}
 For <i class="fab fa-github"></i> **GitHub** and <i class="fab fa-gitlab"></i> **GitLab** there are many such triggers and it is not the goal here to provide a list of them.
 However, we would like to point out, that these triggers generally aim to synchronize the life-cycle of typical workflows.
-For example, pushing a new branch to the remote server will trigger the suggestion to create a Merge/Pull Request. Or merging one branch into another will close any open Merge/Pull Requests that has the one branch as source branch and the other as target branch.
+For example, pushing a new branch to the remote server will trigger the suggestion to create a Merge/Pull Request. Or merging one branch into another will close any open Merge/Pull Requests that has the branch as source branch and the other as target branch.
 
-Even though remote services implement triggers in both directions, the underlying purpose of such triggers it clearly to position tools like Issues and Merge/Pull Requests as interfaces capable to reflect <i class="fab fa-git"></i> events and abstract some <i class="fab fa-git"></i> operations.
+Even though remote services implement triggers in both directions, the underlying purpose of such triggers is clearly to position tools like Issues and Merge/Pull Requests as interfaces capable to reflect <i class="fab fa-git"></i> events and abstract some <i class="fab fa-git"></i> operations.
 {% endif %}
 ```{epigraph}
-In doing so remote services integrate typical <i class="fab fa-git"></i> workflows, like creating or merging a branch, into project management workflows performed with their collaboration tools.
+In doing so, remote services integrate typical <i class="fab fa-git"></i> workflows, like creating or merging a branch, into project management workflows performed with their collaboration tools.
 ```

source/content/project_management/index.md

@@ -3,7 +3,7 @@
 ```{epigraph}
 The process of planning, executing and closing a project within a defined timeline and budged.
 ```
-In this course we will focus on transcribing this very general definition into the context of <i class="fab fa-git"></i> and its remote services, more precisedly <i class="fab fa-github"></i> **GitHub** and <i class="fab fa-gitlab"></i> **GitLab**.
+In this course we will focus on transcribing this very general definition into the context of <i class="fab fa-git"></i> and its remote services, more precisely <i class="fab fa-github"></i> **GitHub** and <i class="fab fa-gitlab"></i> **GitLab**.
 
 {% if slide %}
 <!-- BUILDING THE SLIDES -->

source/content/remote_service_features/access.md

@@ -1,8 +1,8 @@
 ### Access Control
 {% if page %}
-This is a crucial feature remote services provide and is handled somewhat somewhat differently between remotes, unfortunately.
+This is a crucial feature remote services provide and is handled somewhat somewhat differently between remote service providers, unfortunately.
 
-We will discuss this feature in some more detail in the section [Oranizing Projects](../organizing_and_more/index.md#organizing-projects) but in short:
+We will discuss this feature in some more detail in the section [Organizing Projects](../organizing_and_more/index.md#organizing-projects) but in short:
 {% endif %}
 
 Remote services like <i class="fab fa-gitlab"></i> GitLab and <i class="fab fa-github"></i> GitHub, do not just allow repository owners to give access to a repository they host, but they offer:
@@ -11,3 +11,4 @@ Remote services like <i class="fab fa-gitlab"></i> GitLab and <i class="fab fa-g
 - provide controlled **access on organisational levels** ranging over multiple repositories
 - allow to **further distribute access** rights
 - **protect certain resources** (e.g protected `main` branch)
+- **automate access control** by integrating with enterprise identity providers.