Updating information for Contributors

CONTRIBUTING.md

@@ -1,143 +1,177 @@
-<h1><span lang="en">Contributing</span> / <span lang="de">Mitarbeit</span></h1>
+# Contributing :tada:
+Thank you for wanting to help out! :heart:
 
-<span lang="en">Thank you for wanting to help out!</span> <em lang="de">Danke dass du mithelfen möchtest!</em>
+Danke dass du mithelfen möchtest!
+Die deutsche Version dieses Dokuments findest du [hier](./CONTRIBUTING_DE.md).
 
-<em lang="de">Die <a href="#deutsch">deutsche Übersetzung</a> findest du weiter unten.</em>
+# English :milky_way:
 
-## English
+## [Code of conduct](https://www.ecamp3.ch/en/code-of-conduct) :page_with_curl:
 
-### [Code of conduct](https://www.ecamp3.ch/en/code-of-conduct)
+## Workflow :gear:
+This is a basic overview of the workflow, i.e. how we work with the code of eCamp v3. More information about how to set up a development environment on your computer is in the [wiki](https://github.com/ecamp/ecamp3/wiki/installation).
+If something about the setup is unclear, or you run into an error, there are [discussions](https://github.com/ecamp/ecamp3/discussions) on GitHub for you to ask questions and ask for help. :computer:
+### Labels :label:
+Issues are marked with labels and some of them are not self-explanatory and are explained here:
+- **Type-Labels**:
+  Type labels follow the `type: *` format with the options `Frontend`, `Print`, `Deployment` & `API` the architecture for those are partially documented in the [wiki](https://github.com/ecamp/ecamp3/wiki/architecture-frontend)
+- **Needs prototype**: :bulb: If you have an idea how to solve this issue: we'd like to see it. This issue needs a prototype before actual implementation begins since the specifications are somewhat vague. A prototype can be many things, whether your prototype is a sketch, mockup, partial implementation or something else is up to you.
+- **Good first issue**: :green_heart: Beginner friendly issues.
+- **Feature request**: :rocket: An idea/request for a functionality, not ready to be implemented but ready to be discussed.
 
-### Git setup
+### :point_right: Starting with an issue 
+To get started, find an issue that interests you. If you are new, we recommend selecting a [Good first issue](https://github.com/ecamp/ecamp3/labels/Good%20first%20issue).
+Please note that for other issues we recommend ones with the label [Ready for Implementation](https://github.com/ecamp/ecamp3/issues?q=is%3Aopen+is%3Aissue+label%3A%22Ready+for+implementation%22), which signifies that the issue should have clear definitions. If you have any questions, feel free to ask.
+If you are working on an issue, please leave a comment so that we can assign it to you, to make sure that the specifications are still up-to-date, and to prevent two people working on the same issue.
+Alternatively, open a draft pull request and mention the issue ID to signal that you are working on that particular issue.
+Please note that while the wiki can be helpful in understanding the project, it's not exhaustive (meaning there might be parts missing or out of date). If you have any questions, please comment on the issue for clarification. We are happy to help and answer any questions you might have.
+
+### Git setup :octocat:
 
 We use a triangular git workflow. This means that all changes are first pushed to a contributor's fork of the repository, and then the changes are merged into the main fork via a pull request. In practice, setting up this workflow looks as follows:
 
-1. Fork the main repository onto your GitHub account. Let's say your GitHub account is called `your-username`.
+1. Fork the main repository onto your GitHub account. To use the commands your configured git `user.name` must be exactly your git user name. 
+    If you run the code below, and it outputs your GitHub username you are good to go. 
+    ```shell
+    echo $(git config user.name)
+    ```
+    If not you need to replace the `$(git config user.name)` parts with your username or run `git config --global user.name "YourUsername"` with your GitHub username instead of `YourUsername`
+
 
 2. Clone the main repository to your local computer:
 
-   ```bash
+   ```shell
    git clone https://github.com/ecamp/ecamp3.git
    cd ecamp3
    ```
 
 3. Add your fork as a remote:
 
-   ```bash
-   git remote add your-username https://github.com/your-username/ecamp3.git
+   ```shell
+   git remote add "$(git config user.name)" "https://github.com/$(git config user.name)/ecamp3.git"   
    ```
 
 4. Configure the central repo for pulling the current state and your own repo for pushing new changes:
 
-   ```bash
-   git config remote.pushdefault your-username
+   ```shell
+   git config remote.pushdefault "$(git config user.name)"
    git config push.default current
    ```
 
 Once this is set up, you can start coding, and all `git pull` commands should pull from the central repository by default, while all `git push` commands will push to your fork of the project.
 
-### Starting a new feature
+#### Checkout a feature branch
 
 Before starting a new feature, you should do the following steps to start with a clean state that is easily mergeable later:
 
-```bash
+```shell
 git fetch --all
 git checkout origin/devel
 git checkout -b my-new-feature-branch
 ```
 
-### Code formatting
 
-We use cs-fixer for PHP and ESLint and Prettier for Javascript to ensure a common code style. Make sure your code is auto-formatted before comitting and pushing to the repository.
+### Before submitting pull requests :incoming_envelope:
+
+#### Code formatting :art:
 
+We use cs-fixer for PHP and ESLint and Prettier for Javascript to ensure a common code style. Make sure your code is auto-formatted before committing and pushing to the repository.
 We recommend to [configure your IDE](https://github.com/ecamp/ecamp3/wiki/installation-development-windows#code-auto-formatting) such that your code is auto-formatted on save.
 
 Alternatively you can
 
-- run php-cs-fixer and ESLint / Prettier manually before each commit:
-  ```bash
-  docker compose run api composer cs-fix
-  docker compose run frontend npm run lint
-  docker compose run print npm run lint
-  ```
-- set-up a git pre-commit hook to run php-cs-fixer and ESLint automatically before each commit
-
-### Before submitting pull requests
-
-- [x] Did cs-fixer run on all changed or new PHP files?
-- [x] Did ESLint / Prettier run on all changed or new JS / Vue files?
-- [x] Are all variables, classes, functions, comments etc. named or written in English?
-- [x] Did you write tests for any new functionality or adapt the existing tests for changed functionality?
-- [x] Are all passwords, credentials and local configuration removed from the code changes?
-- [x] Do all changed files contain some important changes (as opposed to e.g. only whitespace changes)?
-- [x] Is the fork up-to-date with the central repository and can your changes be merged automatically?
-- [x] Did the GitHub Actions CI build run through without test failures?
-
-## Deutsch
-
-### [Verhaltenskodex](https://www.ecamp3.ch/de/verhaltenskodex)
-
-### Git einrichten
-
-Wir wenden einen triangulären Git-Workflow an. Das bedeutet, dass alle Code-Änderungen zuerst auf dem Fork des Entwicklers veröffentlicht werden, und erst dann werden die Änderungen via Pull Request in das offizielle eCamp3-Repository eingefügt. Um dies einzurichten, befolgen wir folgende Schritte:
-
-1. Erstelle einen persönlichen Fork des zentralen Repositories auf GitHub. Nehmen wir an dein GitHub-Account heisst `your-username`.
-
-2. Klone das originale Repository auf deinen lokalen Computer:
-
-   ```bash
-   git clone https://github.com/ecamp/ecamp3.git
-   cd ecamp3
-   ```
-
-3. Füge deinen Fork als Remote hinzu:
-
-   ```bash
-   git remote add your-username https://github.com/your-username/ecamp3.git
-   ```
-
-4. Konfiguriere Git, sodass es als aktuellen, offiziellen Code-Stand das zentrale Repository und fürs Veröffentlichen neuer Änderungen den Fork verwendet:
-
-   ```bash
-   git config remote.pushdefault your-username
-   git config push.default current
-   ```
-
-Wenn dies eingerichtet ist kannst du loslegen, und alle `git pull`-Befehle sollten standardmässig den Code vom zentralen Repository holen und `git push`-Befehle sollten auf deinen eigenen Fork des Projekts senden.
-
-### Ein neues Feature beginnen
-
-Bevor du etwas am Code änderst, solltest du jeweils die folgenden Schritte durchführen, um mit einem sauberen Stand zu starten der später einfach gemerged werden kann:
-
-```bash
-git fetch --all
-git checkout origin/devel
-git checkout -b my-new-feature-branch
+- <details>
+    <summary>run php-cs-fixer and ESLint / Prettier manually before each commit: (Click me, I am Expandable) </summary>
+
+    ```shell
+    # Frontend fixes in running container
+    docker compose exec frontend npm run lint
+
+    # API/PHP fixes in running container
+    docker compose exec php composer cs-fix
+
+    # Print fixes in running container
+    docker compose exec print npm run lint
+
+    # PDF fixes in running container
+    docker compose exec pdf npm run lint
+
+    # E2E fixes are always run like this
+    docker compose run --rm --entrypoint="npm run lint" e2e
+    ```
+    If you don't have a container of that type running use 'run' instead of 'execute'. Note that this will start a new Docker container (which might not be desired on a device with limited computing resources).
+    ```shell
+    docker compose run frontend npm run lint
+    docker compose run php composer cs-fix
+    docker compose run print npm run lint
+    docker compose run pdf npm run lint
+    ```
+  </details>
+- set up a pre-commit [Git-Hook](https://www.atlassian.com/git/tutorials/git-hooks) to run php-cs-fixer and ESLint automatically before each commit, you can find an example in the [pre-commit.sh](./pre-commit.sh) file. 
+<details>
+  <summary>To use this example as a Git-Hook run the following commands (Click me, I am expandable)</summary>
+    <strong>Consider examining the file before running random code from a public Git repo.</strong>
+
+```shell
+# Ensure the file is executable
+chmod +x .git/hooks/pre-commit
+# Create a link, alternatively use 'cp' instead of 'ln' to copy
+ln ./pre-commit.sh .git/hooks/pre-commit
+# Lets see how long execution takes
+time .git/hooks/pre-commit
 ```
-
-### Quellcode Formatierung
-
-Wir verwenden php-cs-fixer für PHP und ESLint und Prettier für JS um einen gemeinsamen Code Style zu etablieren. Bitte stelle sicher, dass dein Code automatisch richtig formatiert wird, bevor du diesen ins Git repo committest.
-
-Wir empfehlen deine [IDE so zu konfigurieren](https://github.com/ecamp/ecamp3/wiki/installation-development-windows#code-auto-formatting), dass dein Code beim Speichern automatisch richtig formatiert wird.
-
-Alternativ kannst du
-
-- php-cs-fixer und ESLint / Prettier vor jedem commit manuell laufen lassen:
-  ```bash
-  docker compose run api composer cs-fix
-  docker compose run frontend npm run lint
-  docker compose run print npm run lint
-  ```
-- einen git pre-commit hook einrichten, der php-cs-fixer und ESLint vor jedem commit triggert
-
-### Vor dem Einreichen eines Pull Requests
-
-- [x] Wurden alle geänderten oder neuen PHP-Dateien von cs-fixer verarbeitet?
-- [x] Wurden alle geänderten oder neuen JS/Vue-Dateien von ESLint / Prettier bereinigt?
-- [x] Sind alle Variabeln, Klassen, Funktionen, Kommentare, etc. auf englisch benannt?
-- [x] Hast du für neue Funktionalität Tests geschrieben und für geänderte Funktionalität die Tests angepasst?
-- [x] Wurden alle Passwörter, Zugangsdaten und lokale Konfiguration aus den Code-Änderungen entfernt?
-- [x] Enthalten alle geänderten Dateien auch wirklich eine sinnvolle Änderung (im Gegensatz zu z.B. nur Whitespace-Änderungen)?
-- [x] Ist der Fork auf dem aktuellen Stand des zentralen Repositories und können die Änderungen automatisch gemerged werden?
-- [x] Ist der GitHub Actions CI-Build erfolgreich und ohne Test Failures durchgelaufen?
+</details>
+
+#### Checklist :pencil:
+
+We truly value and appreciate every contribution to our project! :heart:
+To make the collaboration smoother and more enjoyable for everyone, 
+we've put together this checklist :scroll:.
+Following it will not only enhance the quality and consistency of your contributions:sparkles:  but also fast-track the review process. :rocket:
+
+
+- [x] **Sync with Central Repository:** :arrows_counterclockwise: Ensure your fork is current with the central repository, facilitating a smooth merge.
+- [x] **Lint:** :wrench: Ensure that linters have run over all new or modified files
+- [x] **Spelling:** :abc: Ensure that linters have run over all new or modified files
+- [x] **Significant Changes:** :mag_right: Confirm that every modified file contributes meaningful content, steering clear of inconsequential changes like mere whitespace adjustments.
+- [x] **Testing:** :test_tube: Write tests for any new features, and update existing ones if you've made changes to functionalities.
+- [x] **Language & Spelling:** :book: Use English for all variable names, class names, functions, comments, etc., and ensure that all added content has been spellchecked.
+- [x] **Sensitive Information:** :no_entry: Before submitting, double-check to ensure no passwords, credentials, or local configurations are present in your changes.
+- [x] **Continuous Integration:** :green_circle: Confirm that the GitHub Actions CI build finishes successfully without test failures.
+
+## Database :floppy_disk:
+
+### Using Dev-Data for Local Development :construction_worker:
+For ease of development and to ensure consistency across local environments, 
+we provide a predefined dataset known as 'Dev-Data'. 
+This dataset is tailored to streamline the testing process and ensure that features, 
+including edge cases, are effectively covered.
+
+### Recommended Test User :bust_in_silhouette:
+To begin with, utilize the `test@example.com / test` user credentials. 
+This user has been populated with a comprehensive set of camps that should suffice for testing most features and scenarios.
+
+### Feedback on Dev-Data :loudspeaker:
+We constantly strive to improve our 'Dev-Data'. 
+If you identify gaps or believe there's an additional scenario it should cover, 
+please open an issue to let us know.
+
+### Documentation :mag:
+For a deeper understanding of 'Dev-Data', you can refer to its dedicated [README](./api/migrations/dev-data/README.md).
+
+### Consistent Testing Across Environments :globe_with_meridians:
+'Dev-Data' is replicated across all development environments. 
+We encourage its use for consistent testing. 
+When reporting an issue or bug, consider referencing a specific example from 'Dev-Data'. 
+Since the data, including IDs, remains consistent, it allows everyone to easily replicate and understand the behavior you're highlighting.
+
+## Discussions :speech_balloon:
+We understand that setting up a development environment can sometimes be tricky, 
+especially with varying systems and configurations.
+If you encounter any issues or face roadblocks during the setup, 
+please don't hesitate to open a Discussion on GitHub. 
+Our core team is happy to help you. 
+In fact, we encourage you to open a Discussion whenever you have a question. 
+Your feedback not only helps us refine the setup process for everyone but also ensures that potential issues are addressed promptly. 
+Remember, our support isn't limited to just setup concerns; 
+you're welcome to initiate discussions on any other topic you encounter. 

CONTRIBUTING_DE.md

@@ -0,0 +1,71 @@
+# Mitarbeit
+Danke dass du mithelfen möchtest!
+
+# Deutsch WIP
+
+### [Verhaltenskodex](https://www.ecamp3.ch/de/verhaltenskodex)
+
+### Git einrichten
+
+Wir wenden einen triangulären Git-Workflow an. Das bedeutet, dass alle Code-Änderungen zuerst auf dem Fork des Entwicklers veröffentlicht werden, und erst dann werden die Änderungen via Pull Request in das offizielle eCamp3-Repository eingefügt. Um dies einzurichten, befolgen wir folgende Schritte:
+
+1. Erstelle einen persönlichen Fork des zentralen Repositories auf GitHub. Nehmen wir an dein GitHub-Account heisst `your-username`.
+
+2. Klone das originale Repository auf deinen lokalen Computer:
+
+   ```bash
+   git clone https://github.com/ecamp/ecamp3.git
+   cd ecamp3
+   ```
+
+3. Füge deinen Fork als Remote hinzu:
+
+   ```bash
+   git remote add your-username https://github.com/your-username/ecamp3.git
+   ```
+
+4. Konfiguriere Git, sodass es als aktuellen, offiziellen Code-Stand das zentrale Repository und fürs Veröffentlichen neuer Änderungen den Fork verwendet:
+
+   ```bash
+   git config remote.pushdefault your-username
+   git config push.default current
+   ```
+
+Wenn dies eingerichtet ist kannst du loslegen, und alle `git pull`-Befehle sollten standardmässig den Code vom zentralen Repository holen und `git push`-Befehle sollten auf deinen eigenen Fork des Projekts senden.
+
+### Ein neues Feature beginnen
+
+Bevor du etwas am Code änderst, solltest du jeweils die folgenden Schritte durchführen, um mit einem sauberen Stand zu starten der später einfach gemerged werden kann:
+
+```bash
+git fetch --all
+git checkout origin/devel
+git checkout -b my-new-feature-branch
+```
+
+### Quellcode Formatierung
+
+Wir verwenden php-cs-fixer für PHP und ESLint und Prettier für JS um einen gemeinsamen Code Style zu etablieren. Bitte stelle sicher, dass dein Code automatisch richtig formatiert wird, bevor du diesen ins Git repo committest.
+
+Wir empfehlen deine [IDE so zu konfigurieren](https://github.com/ecamp/ecamp3/wiki/installation-development-windows#code-auto-formatting), dass dein Code beim Speichern automatisch richtig formatiert wird.
+
+Alternativ kannst du
+
+- php-cs-fixer und ESLint / Prettier vor jedem commit manuell laufen lassen:
+  ```bash
+  docker compose run api composer cs-fix
+  docker compose run frontend npm run lint
+  docker compose run print npm run lint
+  ```
+- einen git pre-commit hook einrichten, der php-cs-fixer und ESLint vor jedem commit triggert
+
+### Vor dem Einreichen eines Pull Requests
+
+- [x] Wurden alle geänderten oder neuen PHP-Dateien von cs-fixer verarbeitet?
+- [x] Wurden alle geänderten oder neuen JS/Vue-Dateien von ESLint / Prettier bereinigt?
+- [x] Sind alle Variabeln, Klassen, Funktionen, Kommentare, etc. auf englisch benannt?
+- [x] Hast du für neue Funktionalität Tests geschrieben und für geänderte Funktionalität die Tests angepasst?
+- [x] Wurden alle Passwörter, Zugangsdaten und lokale Konfiguration aus den Code-Änderungen entfernt?
+- [x] Enthalten alle geänderten Dateien auch wirklich eine sinnvolle Änderung (im Gegensatz zu z.B. nur Whitespace-Änderungen)?
+- [x] Ist der Fork auf dem aktuellen Stand des zentralen Repositories und können die Änderungen automatisch gemerged werden?
+- [x] Ist der GitHub Actions CI-Build erfolgreich und ohne Test Failures durchgelaufen?