Update docs workflow (#1442)

* write section competition

* update workflow overview, add links between setup and workflow for new members

* add infos for cloning the project

* beautify getting-started

* reorder workflow

* Update docs/workflow/competition.md

Co-authored-by: knoellle <[email protected]>

* Update docs/workflow/getting_started.md

Co-authored-by: knoellle <[email protected]>

* address review comments

---------

Co-authored-by: knoellle <[email protected]>

docs/setup/configure_team.md

@@ -1,24 +1,24 @@
 # Configuring Team Specific Data
 
-!!! todo
-
-    This page has to be improved.
-
 ## HULKs Members
 
 There is nothing to do, all the configuration should be ready to go if you cloned the `hulks/hulk` repository.
 
+!!! tip
+
+    Continue reading [here](./upload.md) about how to upload the code to the NAO.
+
 ## Non HULKs Members
 
 ### Set up Team Number
 
 In the HULKs code release, the SPL team number is hardcoded in a few places. Change this to your own team number before continuing.
 
-- `crates/spl_network/src/lib.rs` contains a constant called `HULKS_TEAM_NUMBER`. You may also wish to rename this constant.
-- `tools/pepsi` contains a bunch of `24`s, however most of them are in comments or CLI command help text.
-    - `tools/pepsi/src/parsers.rs` has a default and a check value that use 24 literals.
-- `tools/twix/src/completion_edit.rs` generates IP address suggestions with a hardcoded team number.
-- `etc/parameters/hardware.json` has an attribute called spl for team communication hardcoded to 10024 (10000 + team number).
+-   `crates/spl_network/src/lib.rs` contains a constant called `HULKS_TEAM_NUMBER`. You may also wish to rename this constant.
+-   `tools/pepsi` contains a bunch of `24`s, however most of them are in comments or CLI command help text.
+    -   `tools/pepsi/src/parsers.rs` has a default and a check value that use 24 literals.
+-   `tools/twix/src/completion_edit.rs` generates IP address suggestions with a hardcoded team number.
+-   `etc/parameters/hardware.json` has an attribute called spl for team communication hardcoded to 10024 (10000 + team number).
 
 ### Set up Hardware IDs
 
@@ -28,4 +28,3 @@ For example robot number `21` will always have the IPv4 addresses `10.0.X.21` (w
 
 For each robot you must determine it's head and body IDs and enter them in `etc/parameters/hardware_ids.json`.
 This file is used by [pepsi](../tooling/pepsi.md) and other tools to find the hardware ids belonging to a robot number.
-

docs/setup/development_environment.md

@@ -78,9 +78,14 @@ We use Git to manage all our software.
     You can follow this [guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) to generate and add a key to GitHub.
     If you already have a key, you can skip the part about generating a new one, and simply add your existing key to GitHub.
 
-```sh
-git clone https://github.com/hulks/hulk.git
-```
+To download the repository, run `git clone https://github.com/hulks/hulk.git` in the terminal.
+
+!!! tip
+
+    It's common to not do this in your home directory, but in a separate folder.
+    Most people use a `~/worktree` directory for this.
+    To create this, run `mkdir ~/worktree` and then `cd ~/worktree`.
+    Now you can execute the `git clone` command from above.
 
 ## Build [Pepsi](../tooling/pepsi.md)
 

docs/setup/upload.md

@@ -13,6 +13,10 @@ pepsi upload <NAO>
 Pepsi takes care of downloading and installing the SDK, calling `cargo` to trigger compilation, and uploading the software to the robot.
 When successful, you are presented with a green tick in your shell, and the robot is showing rotating rainbow eyes.
 
+!!! tip
+
+    Continue reading [here](../workflow/overview.md) about our workflow and how to contribute to the project.
+
 ## SDK Management
 
 Pepsi automatically checks for the latest SDK configured in the repository and installs it if necessary.

docs/workflow/competition.md

@@ -1,11 +1,61 @@
-# Competition
-
-TODO
+The HULKs visit various competitions regularly, such as the [RoboCup German Open](https://robocup.de/german-open/) or the international [RoboCup](https://www.robocup.org/).
+During these events, good organization and communication are key to success, a good workflow and not too much stress.
 
 ## Meetings
 
-TODO
+During periods of high activity, a daily Standup meeting is usually held to inform each other about the current status and to coordinate the next steps.
+
+This meeting (as well as all other important events) is documented in the Nextcloud calendar.
+You should have access to it, if not, ask somebody from the team.
+Ideally, you should also have it synced to your phone.
 
 ## Roles
 
-TODO
+To distribute tasks and responsibilities, different roles are assigned to the team members.
+Usually, the roles are assigned during the pregame meeting, only the role of the Head-of-Robots (HoR) is assigned for the whole competition.
+
+!!! note
+
+    During the game, only the Team Captain, Deployer, and Logführer are allowed to stand next to the Game Controller.
+
+### Team Captain
+
+Is usually one of the Dev-Leads, is responsible for the organization of the meetings and the overall schedule.
+Decides which code is deployed.
+
+### Deployer
+
+Merge-squashes different branches and deploys the code to the robots.
+
+??? note "Good to know"
+
+    The deployer should have the necessary hardware or setup for fast deployment.
+    I.e. a fast laptop or a working remote build setup using the HULKs infrastructure.
+    Strong nerves are also a plus, as well as the ability to cope with sudden merge conflicts.
+    This however can be learned and trained.
+
+### Logführer
+
+Is responsible for observing the game and noting down important events and things that need to be improved.
+
+### Head-of-Robots (HoR)
+
+Is responsible for the robots and the hardware, as well as all interactions with [URG](https://unitedrobotics.group/en/robots/nao).
+Keeps the [Roboboboard](https://github.com/orgs/HULKs/projects/3) up to date and selects the robots for the game, as well as their number.
+
+!!! tip "Important"
+
+    This role is extremely important, as the hardware status (especially in the later games) is crucial for the performance.
+    Also, having a good relationship with URG can be beneficial for the team.
+
+## Game Schedule
+
+For games, a strict schedule is created, which looks like this:
+
+-   90 minutes prior: Pregrame Meeting <br>
+    Here, the roles are assigned and last steps and important tasks before the game are discussed.
+-   45 minutes prior: Code at deployer <br>
+    All branches are ready to be merged and deployed.
+    Sometimes parameter changes are still made after this stage.
+-   30 minutes prior: Golden Goal <br>
+    A kick-off against an empty field is performed. This is the final test before the game.

docs/workflow/development.md

@@ -1,6 +1,15 @@
 # Development
 
-TODO
+-   Development workflow
+    -   GitHub
+        -   CI
+        -   Board
+    -   Meetings
+        -   Test games
+    -   Test-driven development
+        -   Unit testing
+        -   Webots
+        -   Behavior Simulator
 
 ## GitHub
 
@@ -12,48 +21,48 @@ TODO
 
 ### The Development Project
 
-At HULKs we use a quite heavily modified version of the [KanBan workflow](https://en.wikipedia.org/wiki/Kanban_(development)). The *Current Board*s **purpose** is to **visualize** our current development status. The modifications were mainly done to address the fact that we do not have fixed working hours. Limiting the amount of cards that are in progress does not work. Especially for members that are not present on a daily basis. The *List* is mainly for organizing multiple iterations for a more long-term overview (important for dev-leads).
+At HULKs we use a quite heavily modified version of the [KanBan workflow](<https://en.wikipedia.org/wiki/Kanban_(development)>). The *Current Board*s **purpose** is to **visualize** our current development status. The modifications were mainly done to address the fact that we do not have fixed working hours. Limiting the amount of cards that are in progress does not work. Especially for members that are not present on a daily basis. The _List_ is mainly for organizing multiple iterations for a more long-term overview (important for dev-leads).
 
 #### Terms
 
 **Assignee:** The person that is responsible for a card (has the **exclusive** right to move a card(!) as soon as there is one). The assignee's job depends on the Kanban column:
 
-- No assignee: *Open*, *Done*
-- Assignee works on issue/pull request (if more or less progress happens on it): *In Progress*
-- Assignee is responsible to bring a pull request to `main` (e.g. reviewer, tester): *Request for Review*
+-   No assignee: _Open_, _Done_
+-   Assignee works on issue/pull request (if more or less progress happens on it): _In Progress_
+-   Assignee is responsible to bring a pull request to `main` (e.g. reviewer, tester): _Request for Review_
 
-**Note** that github distinguishes between *reviewers* and *assignees*. We also do that. Kind of. While the *assignee* (in most cases one person) is responsible for the card and bring the branch into the main, the *reviewer(s)* (can be more than one) can review the code at any time in addition to the notes that were given by the *assignee*. In general: The more reviewers the better the resulting code (That being said: feel free to review code).
+**Note** that github distinguishes between _reviewers_ and _assignees_. We also do that. Kind of. While the _assignee_ (in most cases one person) is responsible for the card and bring the branch into the main, the _reviewer(s)_ (can be more than one) can review the code at any time in addition to the notes that were given by the _assignee_. In general: The more reviewers the better the resulting code (That being said: feel free to review code).
 
-| *Open* | *In Progress* | *Request for Review* | *Done* |
-|--------|---------------|----------------------|--------|
-|--------| Developer     | Reviewer             |--------|
+| _Open_   | _In Progress_ | _Request for Review_ | _Done_   |
+| -------- | ------------- | -------------------- | -------- |
+| -------- | Developer     | Reviewer             | -------- |
 
 **Author:** The person that created this card (issue/pull request). Responsible for answering questions (issues/pull requests) and implement/discuss requested changes (pull requests).
 
 #### Open
 
-The *Open* section contains by the dev-leads selected **issues** that are important and of high priority for the current iteration. However, if you want to work on issues that are not in *Open*: Feel free to do so.
+The _Open_ section contains by the dev-leads selected **issues** that are important and of high priority for the current iteration. However, if you want to work on issues that are not in _Open_: Feel free to do so.
 
-**Move** (or **add**) an issue into *In Progress* **and** assign yourself when you started working on it.
+**Move** (or **add**) an issue into _In Progress_ **and** assign yourself when you started working on it.
 
 #### In Progress
 
-The *In Progress* section contains:
+The _In Progress_ section contains:
 
-- **issues** that have an assignee, but no open pull request. As soon as there is an open pull request fixing this issue, the issue card should be replaced by this pull request card (removing the Issue from the Project but not closing it as it is not fixed in the main yet). The issue must then be mentioned with the `fixes #Issue_NO` in the pull requests description.
-- **pull requests** that are not ready for review yet and are currently wip.
+-   **issues** that have an assignee, but no open pull request. As soon as there is an open pull request fixing this issue, the issue card should be replaced by this pull request card (removing the Issue from the Project but not closing it as it is not fixed in the main yet). The issue must then be mentioned with the `fixes #Issue_NO` in the pull requests description.
+-   **pull requests** that are not ready for review yet and are currently wip.
 
 **Note:** `fixes #Issue_NO` is a keyword on github. Github will automatically close the mentioned issue whenever the corresponding pull request was merged. Do **not** close issues that have not being fixed in the main yet (even if there is a pull request for it)!
 
-**Move** a pull request into *Request for Review* when you have finished your work **and** tested the pull request yourself on relevant platforms. At this stage a pull requests' description should be finalized (fill out the template properly).
+**Move** a pull request into _Request for Review_ when you have finished your work **and** tested the pull request yourself on relevant platforms. At this stage a pull requests' description should be finalized (fill out the template properly).
 
 #### Request for Review
 
-The *Request for Review* section contains **pull requests** that are ready to be reviewed. They don't need to be finished™ for that, they can still be a *draft pull request*.
+The _Request for Review_ section contains **pull requests** that are ready to be reviewed. They don't need to be finished™ for that, they can still be a _draft pull request_.
 
 **Note:** This section is a prioritized FIFO queue. Add new cards at the bottom. The head of development might decide to move it further up if the pull request is rather important.
 
-**Note:** Enable *auto-merge* if your pull request is not a *draft pull request*
+**Note:** Enable _auto-merge_ if your pull request is not a _draft pull request_
 
 Assign yourself if you want to review this pull request.