Merge pull request #332 from una-auxme/254-feature-create-a-document-…

…for-best-practices-during-the-development-phase

Updated docs to new code structure & first steps

.github/workflows/build.yml

@@ -45,9 +45,10 @@ jobs:
         uses: docker/build-push-action@v3
         with:
           context: .
-          file: ./build/docker/build/Dockerfile
+          file: ./build/docker/agent/Dockerfile
           push: true
           # tag 'latest' and version on push to main, otherwise use the commit hash
           tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
           cache-from: type=gha
           cache-to: type=gha,mode=max
+          build-args: USERNAME=paf,USER_UID=1000,USER_GID=1000

build/agent_service.yaml

@@ -34,7 +34,7 @@ services:
     volumes:
       - /tmp/.X11-unix:/tmp/.X11-unix
       # if you change the volume here also change the copy command
-      # in ``build/docker/build/Dockerfile
+      # in ``build/docker/agent/Dockerfile
       - ../:/workspace
       # mount git config for dvc
       - ../.gitconfig:/home/carla/.gitconfig

doc/development/README.md

@@ -1,22 +1,28 @@
-# Development guidelines
+# Development in PAF
+
+## First steps
+
+If this is your first time working with the project you can follow the first steps in [/doc/development/first_steps.md](/doc/development/first_steps.md).
+
+## Development guidelines
 
 If you contribute to this project please read the following guidelines first:
 
 1. [Documentation Requirements](./documentation_requirements.md)
 2. [Linting](./linting.md)
-3. [Coding style](./coding_style.md)
-4. [Git Style](./git_workflow.md)
-5. [Reviewing](./review_guideline.md)
-6. [Project management](./project_management.md)
-7. Github actions
+3. [Git Style](./git_workflow.md)
+4. [Reviewing](./review_guideline.md)
+5. [Project management](./project_management.md)
+6. Github actions
    1. [linting action](./linter_action.md)
    2. [build action](./build_action.md)
-8. [Install python packages](./installing_python_packages.md)
-9. [Discord Webhook Documentation](./discord_webhook.md)
+   3. [drive action](./drive_action.md)
+7. [Install python packages](./installing_python_packages.md)
+8. [Discord Webhook Documentation](./discord_webhook.md)
 
 ## Templates
 
-Templates for documentation and code are provided in [`doc/development/templates`](./templates).
+Templates for documentation and code are provided in [`doc/development/templates`](./templates). These templates are to be used for new files that are added to the project.
 
 ### [`template_class.py`](./templates/template_class.py)
 

doc/development/build_action.md

@@ -2,13 +2,9 @@
 
 (Kept from previous group [paf22])
 
-**Summary:** This page explains the GitHub build action we use to first:
-
-- create an executable image of our work
-- evaluate our Agent with the leaderboard
+**Summary:** This page explains the GitHub build action we use to create an executable image of our work.
 
 - [GitHub actions](#github-actions)
-  - [Table of contents](#table-of-contents)
   - [General](#general)
   - [The Dockerfile (`build/docker/build/Dockerfile`)](#the-dockerfile-builddockerbuilddockerfile)
   - [The `build-and-push-image` job](#the-build-and-push-image-job)
@@ -18,13 +14,6 @@
     - [4. Bump version and push tag (`mathieudutour/github-tag-action`)](#4-bump-version-and-push-tag-mathieudutourgithub-tag-action)
     - [5. Get commit hash](#5-get-commit-hash)
     - [6. Build and push Docker image](#6-build-and-push-docker-image)
-  - [The drive job](#the-drive-job)
-    - [1. Checkout repository (`actions/checkout@v3`)](#1-checkout-repository-actionscheckoutv3-1)
-    - [2. Run agent with docker-compose](#2-run-agent-with-docker-compose)
-    - [3. Copy simulation results file out of container](#3-copy-simulation-results-file-out-of-container)
-    - [4. Stop docker-compose stack](#4-stop-docker-compose-stack)
-    - [5. Comment result in pull request `actions/github-script@v6`](#5-comment-result-in-pull-request-actionsgithub-scriptv6)
-  - [Simulation results](#simulation-results)
 
 ## General
 
@@ -80,60 +69,3 @@ the [GitHub Actions cache](https://docs.docker.com/build/building/cache/backends
 is used to cache the image after build.
 If the action is run on a branch other than `main`, the image is tagged with the commit hash from Step 5.
 Otherwise, the image is tagged with both the tag created in Step 4 and `latest`.
-
-## The drive job
-
-The `drive` job is executed conditionally on `pull_request`, after the build successfully ran through.
-
-### 1. Checkout repository ([`actions/checkout@v3`](https://github.com/actions/checkout))
-
-Same step as in the [build job](#1-checkout-repository--actionscheckoutv3-)
-
-### 2. Run agent with docker-compose
-
-Runs the agent with the [`build/docker-compose.cicd.yaml`](../../build/docker-compose.cicd.yaml) that only contains the
-bare minimum components for test execution:
-
-- Carla Simulator
-- roscore
-- Agent container, run through the
-  Carla [`leaderboard_evaluator`](https://github.com/carla-simulator/leaderboard/blob/leaderboard-2.0/leaderboard/leaderboard_evaluator.py).
-
-### 3. Copy simulation results file out of container
-
-Copies the created `simulation_results.json` file out of the agent container into the current container
-
-### 4. Stop docker-compose stack
-
-Stops the remaining containers (Carla, roscore) and removes the volumes with:
-`$ docker-compose down -v`.
-
-This step is important to clean up the remaining containers to have a clean run everytime. This is also the reason for
-the `if: always()`, that ensures step execution.
-
-### 5. Comment result in pull request [`actions/github-script@v6`](https://github.com/marketplace/actions/github-script)
-
-This steps uses a JS script to parse the simulation results and add a comment with a results table to the corresponding
-pull request.
-
-An example comment for this would be:
-
-## Simulation results
-
-| Metric                               | Value   |
-|--------------------------------------|---------|
-| Avg. driving score                   | 0.06006 |
-| Avg. route completion                | 0.22    |
-| Avg. infraction penalty              | 0.273   |
-| Collisions with pedestrians          | 0.0     |
-| Collisions with vehicles             | 62.046  |
-| Collisions with layout               | 62.046  |
-| Red lights infractions               | 0.0     |
-| Stop sign infractions                | 0.0     |
-| Off-road infractions                 | 0       |
-| Route deviations                     | 0.0     |
-| Route timeouts                       | 62.046  |
-| Agent blocked                        | 0.0     |
-| Yield emergency vehicles infractions | 0.0     |
-| Scenario timeouts                    | 62.046  |
-| Min speed infractions                | 0.0     |