Merge pull request #12 from t4d-gmbh/5-organizing-projects-and-more

5 organizing projects and more

source/content/organizing_and_more/differences.md

@@ -0,0 +1,17 @@
+## Differences Between GitHub and GitLab
+
+:::{admonition} <i class="far fa-folder-open"></i> Project {math}`\neq` {octicon}`project` Project
+:class: warning
+In <i class="fab fa-gitlab"></i> **GitLab** a <i class="fab fa-git"></i> repository is represented in a <i class="far fa-folder-open"></i> Project while on <i class="fab fa-github"></i> **GitHub** it is a {octicon}`repo` Repository.
+
+What is refered to as {octicon}`project` Project in <i class="fab fa-github"></i> **GitHub** shares more similarities with a <i class="fas fa-people-roof"></i> Subgroup in <i class="fab fa-gitlab"></i> **GitLab**.
+:::
+
+### Access Rights and Sub-Groups
+
+| Feature                     | GitHub                                      | GitLab                                      |
+|-----------------------------|---------------------------------------------|---------------------------------------------|
+| **Access Control**          | Managed through nested Teams and Repository settings | Managed through Subgroups and Repository settings  |
+| **Permission Levels**       | Read, Triage, Write, Maintain, Admin       | Guest, Reporter, Developer, Maintainer, Owner |
+| **Inheritance**             | Permissions are inherited from organization-level settings to Teams and child-Teams. | Subgroups inherit permissions from parent (Sub-)Groups, but cannot revoke them |
+| **Additional Rights**       | Can assign different permissions to Teams   | Can grant additional rights in Subgroups   |

source/content/organizing_and_more/example_situation_accademia.md

@@ -0,0 +1,24 @@
+{% if build == "pages" %}
+## Possible Challenges Faced by Research Groups
+
+Imagine a research group at a university, bustling with brilliant minds and groundbreaking ideas. 
+However, their collaboration is hindered by a chaotic workflow. 
+Emails are overflowing with attachments, version control is a nightmare, and crucial updates are often lost in the shuffle. 
+Team members frequently overwrite each other’s work or share code snippets by email, leading to frustration and wasted time.
+
+Tasks are managed haphazardly, with no clear system to track progress or assign responsibilities. 
+Important milestones are missed, and the lack of standardized documentation of implementations or even ideas makes it difficult for new members to get up to speed and can lead to knowledge drain when team members leave.
+Data integrity is compromised, and integrating contributions from different team members is a constant struggle.
+
+{% elif build == "slides" %}
+<!-- BUILDING THE SLIDES -->
+## Possible Challenges Faced by Research Groups
+
+- *Chaotic Workflow*: Inefficient collaboration despite brilliant ideas.
+- *Email Overload*: Attachments and code snippets lost in email chains.
+- *Version Control Issues*: Frequent overwriting of work, leading to frustration.
+- *Disorganized Task Management*: Lack of a clear system for monitoring progress or assigning duties.
+- *Lack of Standardized Documentation*: Difficult for new members to get up to speed; knowledge drain when members leave.
+- *Data Integrity Compromised*: Struggles with integrating contributions from different team members.
+
+{% endif %}

source/content/organizing_and_more/github_key_elements.md

@@ -0,0 +1,45 @@
+### Key Elements
+
+{% if page %}::::{tabs}{% endif %}
+{% if page %}:::{tab}{% else %}:::{card}{% endif%} {octicon}`person` Users
+Individual accounts that can own Organizations, (nested-)Teams, and Repositories.
+They can be assigned to different project management elements and roles like {octicon}`issue-opened` Issues, {octicon}`git-pull-request` Pull Requests, {octicon}`milestone` Milestones, {octicon}`project`Projects, etc.
+{% if page %}
+```{admonition} Details
+:class: tip, dropdown
+- Individual accounts that can access and contribute to repositories.
+- Can be assigned different [roles & permissions](https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github) within Organizations, (nested-)Teams and Repositories.
+```
+{% endif %}
+:::
+{% if page %}:::{tab}{% else %}:::{card}{% endif%} {octicon}`organization` Organizations
+Shared accounts for collaboration across multiple projects. 
+
+{% if page %}
+```{admonition} Details
+:class: tip, dropdown
+They are a collection of repositories and users. In academia, they can provide a hub for showcasing research projects, coursework, and collaborative efforts.
+```
+{% endif %}
+:::
+{% if page %}:::{tab}{% else %}:::{card}{% endif%} {octicon}`people` Teams
+Teams are groups of organization members (not outside collaborators) with access to specific repositories. 
+To reflect a group's hierarchy, teams can be nested within other teams.
+Child teams inherit the permissions of their parent team. 
+{% if page %}
+```{admonition} Details
+:class: tip, dropdown
+Hierarchies of Teams can be used to manage permissions and access to repositories. 
+In an academic setting, teams can be created e.g. for a group of students working on a project or a research team collaborating on a paper.
+```
+{% endif %}
+:::
+{% if page %}:::{tab}{% else %}:::{card}{% endif%} {octicon}`repo` Repositories
+Containers for project files, code, and documentation. {% if page %}
+```{admonition} Details
+:class: tip, dropdown
+Repositories can be public or private and can be used to organize and manage project files. In academia, repositories can store research data, code, and manuscripts.
+```
+{% endif %}
+:::
+{% if page %}::::{% endif %}

source/content/organizing_and_more/github_org_elements.md

@@ -1,3 +1,23 @@
-## GitHub's organization structure
+## <i class="fab fa-github"></i> **GitHub**'s Organization Structure
+
+{% if slide %}
+<!-- BUILDING THE SLIDES -->
+```{toctree}
+:maxdepth: 2
+
+./github_key_elements
+./github_org_setup
+
+```
+{% else %}
+<!-- BUILDING THE PAGES -->
+<!-- build the page content here -->
+```{include} ./github_key_elements.md
+```
+```{include} ./github_org_setup.md
+```
+```{include} ./github_setup_usage.md
+```
+{% endif %}
+
 
-_TODO:_ talk about owners, organizations, projects

source/content/organizing_and_more/github_org_setup.md

@@ -0,0 +1,49 @@
+### Setting up a GitHub Organization {octicon}`organization`
+
+{% if page %}
+:::{margin} <i class="fab fa-github"></i> Roles in Organizations:
+  - **Read**: Can view repositories and issues.
+  - **Triage**: Can manage issues and pull requests.
+  - **Write**: Can push code, manage issues, and pull requests.
+  - **Maintain**: Full access to manage non-destructive, non-sensitive settings.
+  - **Admin**: Complete control over the repository and its settings, incl. managing security and deleting the repository.
+:::
+{% endif %}
+
+{% if page %}
+In **GitHub** Organization members can have different access levels to the repositories that are owned by the Organization.
+Organization owners can manage the access rights of members and create Teams to group members with similar roles or responsibilities.
+They can also set base permissions for the Organization and its repositories.
+Organization owners have admin access to all repositories and can manage the Organization's settings.
+
+:::{margin} <i class="fab fa-github"></i> Enterprise Cloud:
+GitHub Enterprise Cloud offers additional security features and compliance tools for organizations, i.a. SAML single sign-on, automated security updates, and advanced auditing, and Organization specific roles.
+:::
+{% endif %}
+
+For a small organization, like a research group or small company, we suggest the following approach:
+
+{% if page %}##### {% endif %}1. **Create a {octicon}`organization` Organization** {% if slide %} Invite all permanent research group members with "Write" or "Maintain" Roles.
+{% else %}
+  - Create a new Organization to represent your research group.
+    :::{note} Assign multiple Owners to the Organization.
+    If an organization only has one owner, the organization's projects can become inaccessible if the owner is unreachable.
+    :::
+  - Unlike in GitLab, the visibility of an Organization in GitHub is always public. However, repositories owned by the Organization can be private.
+{% endif %}
+
+{% if page %}##### {% endif %}2. **Create {octicon}`people` Teams** {% if slide %} Represent your research-groups hierarchy with Teams and Teams-of-Teams (child Teams). 
+This can be useful for managing permissions and access to repositories.
+{% else %}
+  - Create Teams to represent different research groups, projects, or labs within the Organization.
+  - Assign members to the Teams based on their roles and responsibilities.
+    :::{tip}
+    Assign two or more Organization members as *Team Maintainers* to help manage the Team's settings and permissions.
+    :::
+  - Teams can be nested within other Teams to reflect the research group's hierarchy.
+{% endif %}
+
+{% if page %}##### {% endif %}3. **Invite additional {octicon}`person` Users** {% if slide %} Add ext. collaborators and temp. members who are not part of your {octicon}`organization` Organization directly to {octicon}`repo` Repositories.
+{% else %}
+  - Add external collaborators who are not part of your {octicon}`organization`Organization directly to the corresponding {octicon}`repo`Repositories.
+{% endif %}

source/content/organizing_and_more/github_setup_usage.md

@@ -0,0 +1,16 @@
+### GitHub's Organization Structure in Action
+
+In an academic context, GitHub's organization structure can be leveraged to streamline collaboration and project management. Here's how it might look:
+
+- {octicon}`organization` **Organization Creation**: Your university's research lab could create an organization on GitHub to host various research projects. The faculty members could be the owners of the organization, overseeing the projects and managing access.
+
+- {octicon}`people` **Team Formation**: Create teams within the organization for different research groups or projects. Each team would have access to specific repositories based on their roles and responsibilities. This might be useful for managing permissions and collaboration within the lab. For example, a team of students working on a specific project could have access to the corresponding repository.
+
+- {octicon}`repo` **Repository Management**: Each research project could have its own repository within the organization (or multiple repositories). These repositories could contain code, data, manuscripts, and other project-related files. By using repositories, you can maintain version control, track changes, and collaborate effectively on research projects.
+
+- **Progress Tracking**: Track the research project's progress using {octicon}`issue-opened` issues, {octicon}`project` project boards (which can be linked to multiple repositories), and {octicon}`git-pull-request;0.8em` pull requests within the repositories. This would help in managing tasks, tracking {octicon}`milestone;0.8em` milestones, and reviewing contributions from team members.
+
+#### Collaborating with External Partners
+
+Invite collaborators to specific {octicon}`repo`repositories within the {octicon}`organization`Organization, enabling them to contribute to the project. 
+This can be particularly useful when working with industry partners, other research groups, or open-source communities.

source/content/organizing_and_more/gitlab_key_elements.md

@@ -0,0 +1,51 @@
+### Key Elements
+
+{% if page %}::::{tabs}{% endif %}
+{% if page %}:::{tab}{% else %}:::{card}{% endif%} <i class="fas fa-user"></i> Users
+Individual accounts that can own Projects and roles in other Projects or (Sub-)Groups.
+{% if page %}
+```{admonition} Details
+:class: tip, dropdown
+- Individual accounts that can access and contribute to repositories.
+- Can be assigned different [roles & permissions](https://docs.gitlab.com/ee/user/permissions.html) within (Sub-)Groups and Projects.
+```
+{% endif %}
+:::
+{% if page %}:::{tab}{% else %}:::{card}{% endif%} <i class="fas fa-people-group"></i> Groups
+Collection of Users and Subgroups that can own Projects and [roles & permissions](https://docs.gitlab.com/ee/user/permissions.html) in other Projects or (Sub-)Groups.
+{% if page %}
+```{admonition} Details
+:class: tip, dropdown
+- Can own Projects and be assigned different [roles & permissions](https://docs.gitlab.com/ee/user/permissions.html) within other (Sub-)Groups and Projects.
+- Contain a collection of Users (i.e. Members) with individual roles (i.e. access rights)
+- Can own Subgroups
+- Allow for centralized management of permissions and settings.
+- Provide management tools, like milestones and Kanban boards to manage all Issues and Merge Requests of related Projects.
+```
+{% endif %}
+:::
+{% if page %}:::{tab}{% else %}:::{card}{% endif%} <i class="fas fa-people-roof"></i> Subgroups
+A Group that is owned by a parent Group inheriting its members.
+{% if page %}
+```{admonition} Details
+:class: tip, dropdown
+- Nested groups within a parent (Sub-)Group.
+- Inherit Users along with their roles from all parent (Sub-)Groups.
+- Share all other features of Groups
+```
+{% endif %}
+:::
+{% if page %}:::{tab}{% else %}:::{card}{% endif%} <i class="far fa-folder-open"></i> Projects
+Represent the actual <i class="fab fa-git"></i> repositories with an owner, as well as, [roles & permissions](https://docs.gitlab.com/ee/user/permissions.html) for other Users and (Sub-)Groups.
+{% if page %}
+```{admonition} Details
+:class: tip, dropdown
+- Projects are the core units of storage for <i class="fab fa-git"></i> repositories.
+- Each project is owned either by a User, a Group or a Subgroup.
+- Projects can contain their own Issues, Merge Requests, and project settings.
+- Repositories can be public or private, depending on the desired visibility.
+```
+{% endif %}
+:::
+{% if page %}::::{% endif %}
+

source/content/organizing_and_more/gitlab_org_elements.md

@@ -0,0 +1,26 @@
+## <i class="fab fa-gitlab"></i> **GitLab**'s Organization Structure
+{% if page %}**GitLab** implements a nesting approach when it comes to access rights and structuring multiple projects and related users.
+It relies on only two building blocks, Users and (Sub-)Groups, for managing access rights.{% endif %}
+&nbsp;
+```{epigraph}
+In **GitLab** nested usergroups are used to manage access rights to <i class="fab fa-git"></i> repositories.
+```
+{% if slide %}
+<!-- BUILDING THE SLIDES -->
+```{toctree}
+:maxdepth: 2
+
+./gitlab_key_elements
+./gitlab_org_setup
+
+```
+{% else %}
+<!-- BUILDING THE PAGES -->
+<!-- build the page content here -->
+```{include} ./gitlab_key_elements.md
+```
+```{include} ./gitlab_org_setup.md
+```
+```{include} ./gitlab_setup_usage.md
+```
+{% endif %}

source/content/organizing_and_more/gitlab_org_setup.md

@@ -0,0 +1,62 @@
+### Setting up an Organization
+
+{% if page %}
+:::{margin} <i class="fab fa-gitlab"></i> Roles:
+  - **Guest**: Limited access to view Issues and Merge Requests.
+  - **Reporter**: Can view and create Issues, but cannot push code.
+  - **Developer**: Can push code, manage Issues, and Merge Requests.
+  - **Maintainer**: Full access to manage the Project and settings.
+  - **Owner**: Complete control over the Group and its Subgroups.
+:::
+{% endif %}
+{% if page %}
+**GitLab**'s approach to manage access control requires some care in order to create a organizational setup that facilitates collaboration and project management.
+The key aspect to take into account is the inheritance of Members (i.e. Users) along with their roles (i.e. access rights).
+{% endif %}
+
+For a small organization, like a research group or small company, we suggest the following approach:
+
+{% if page %}##### {% endif %}1. **Create a <i class="fas fa-people-group"></i> Group** {% if slide %} Invite all permanent group members as "Developer" or "Reporter".
+{% else %}
+  - Create a new Group to represent your organization.
+  - Set the [visibility level](https://docs.gitlab.com/ee/user/public_access.html).
+    :::{note}
+    Restrictions in the visibility are inherited, i.e. in a _private_ Group you can only have _private_ Projects.
+    However, in a _public_ Group it is possible to have _private_ Projects.
+    :::
+  - Decide on the transparency level within the group by [identifying a default role](https://docs.gitlab.com/ee/user/permissions.html) for members of the Group.
+    :::{tip}
+    [Developer](https://docs.gitlab.com/ee/user/permissions.html#repository) is a good default role, as it allows to view all Projects and suggest edits without being able to change the content of a Project completely.
+    :::
+  - Invite all permanent group members.
+  - Designate 1-2 Users with elevated privileges.
+    We recommend to have more than one [Owner and some Maintainers](https://docs.gitlab.com/ee/user/permissions.html#repository).
+{% endif %}
+
+{% if page %}##### {% endif %}2. **Create <i class="fas fa-people-roof"></i> Subgroups** {% if slide %} With designated Owners for distinct research areas, projects, labs, etc.
+{% else %}
+  - Fill in the short description to clarify what this Subgroup is about.
+  - Designate 1-2 Users with elevated privileged (i.e. designate another Owner and maybe some Maintainers)
+    :::{tip}
+    You can invite Users that are already part of any parent (Sub-)Group again and "escalate" their role in this Subgroup.
+    In doing so you can designate Owners or Maintainers of only Subgroups.
+
+    ```{note}
+    The inverse is not possible: You can only give a User **more rights** than what was already inherited from the parent (Sub-)Group.
+    ```
+    :::
+{% endif %}
+
+{% if page %}##### {% endif %}3. **Invite additional <i class="fas fa-user"></i> Users** {% if slide %} Add ext. collaborators and temp. members directly to Subgroups
+{% else %}
+  - Add external collaborators and short-term members of your group directly into the corresponding Subgroups.
+    :::{tip}
+    It is also possible to add entire (Sub-)Groups which can be a great setup for a collaborative project between two or more research groups.
+    :::
+{% endif %}
+
+{% if page %}##### {% endif %}4. **Gradually <i class="fas fa-universal-access"></i> escalate Privileges**{% if slide %} Members of Subgroups should be able to take advantage of **GitLab**'s features
+{% else %}
+  - Elevate the privileges of <i class="fas fa-user"></i> Users in Subgroups to make sure that the members of a Subgroup can take advantage of **GitLab**'s remote features to the fullest extent.
+  - Think of re-inviting members of parent (Sub-)Groups to elevate their roles.
+{% endif %}

source/content/organizing_and_more/gitlab_setup_usage.md

@@ -0,0 +1,29 @@
+### **GitLab**'s Organization Structure in Action
+
+In an academic context, **GitLab**'s organizational structure can be leveraged to streamline collaboration and project management.
+Here's how it might look:
+
+- **Group Creation**: Your university's research lab could create a Group on **GitLab** to host various research projects.
+  Faculty members could be assigned the role of Owners of the Group, overseeing the projects and managing access.
+
+- **Sub-Group Formation**: Create Subgroups within the main Group for different research areas or projects.
+  Each Subgroup would have access to specific repositories based on their roles and responsibilities.
+  This structure is useful for managing permissions and collaboration within the lab.
+  For example, a Subgroup for a specific research project could have its own dedicated repositories.
+
+- **Repository Management**: Each research project could have its own repository within the relevant Subgroup (or multiple repositories).
+  These repositories could contain code, data, manuscripts, and other project-related files.
+  By using repositories, you can maintain version control, track changes, and collaborate effectively on research projects.
+
+- **Progress Tracking**: Track the research project's progress using Issues, issue boards (which can aggregate all Issues in a Subgroup), and Merge Requests within the repositories.
+  This would help in managing tasks, tracking Milestones, and reviewing contributions from team members.
+
+  :::{note}
+  In some cases, the administrative hierarchy of the faculty is not suitable to be mirrored in **GitLab**'s Group/Subgroup structure. 
+  For example, if a faculty member is barely involved in hands-on research, a second Group-Owner might relieve them of the burden of managing **GitLab** access rights.
+  :::
+
+### Collaborating with External Partners
+
+Invite collaborators to specific Projects or Subgroups within the Group, enabling them to contribute to a project.
+This can be particularly useful when working with industry partners, other research groups, or open-source communities.