Merge branch 'develop' into feature/saml2-audit

.github/PULL_REQUEST_TEMPLATE.md

@@ -94,6 +94,7 @@ Prerequisites:
 <!-- All PRs that might affect the exam mode (e.g. change a client component that is also used in the exam mode) need an additional verification that the exam mode still works. -->
 
 #### Performance Review
+<!-- See [Large Course Setup](https://github.com/ls1intum/Artemis/tree/develop/supporting_scripts/course-scripts/quick-course-setup) for the automation script that handles large course setup. -->
 - [ ] I (as a reviewer) confirm that the client changes (in particular related to REST calls and UI responsiveness) are implemented with a very good performance even for very large courses with more than 2000 students.
 - [ ] I (as a reviewer) confirm that the server changes (in particular related to database calls) are implemented with a very good performance even for very large courses with more than 2000 students.
 #### Code Review

docker/artemis/config/playwright.env

@@ -27,6 +27,8 @@ ARTEMIS_CONTINUOUSINTEGRATION_EMPTYCOMMITNECESSARY="true"
 
 ARTEMIS_APOLLON_CONVERSIONSERVICEURL="https://apollon.ase.in.tum.de/api/converter"
 
+ARTEMIS_TELEMETRY_ENABLED="false"
+
 # Token is valid 3 days
 JHIPSTER_SECURITY_AUTHENTICATION_JWT_TOKENVALIDITYINSECONDS="259200"
 # Token is valid 30 days
@@ -38,6 +40,7 @@ INFO_IMPRINT="https://ase.in.tum.de/lehrstuhl_1/component/content/article/179-im
 INFO_TESTSERVER="true"
 INFO_TEXTASSESSMENTANALYTICSENABLED="true"
 INFO_STUDENTEXAMSTORESESSIONDATA="true"
+INFO_OPERATORNAME="TUM"
 
 LOGGING_FILE_NAME="/opt/artemis/data/artemis.log"
 

docs/.gitignore

@@ -1,3 +1,6 @@
 _build/
 .venv/
 .idea/
+__pycache__/
+.env
+venv

docs/README.md

@@ -56,15 +56,34 @@ For pull requests, the documentation is available at `https://artemis-platform--
 RtD will build and deploy changes automatically.
 
 ## Installing Sphinx Locally
+
+Optionally, create and activate a virtual environment:
+```
+python3 -m venv venv
+```
+On Linux or macOS:
+```
+source venv/bin/activate
+```
+On Windows (CMD):
+```
+venv\Scripts\activate.bat
+```
+On Windows (PowerShell):
+```
+venv\Scripts\Activate.ps1
+```
+
+
 [Sphinx] can run locally to generate the documentation in HTML and other formats.
 You can install Sphinx using `pip` or choose a system-wide installation instead.
 When using pip, consider using [Python virtual environments].
 ```bash
-pip install -r requirements.txt --break-system-packages
+pip install -r requirements.txt
 ```
 or
 ```bash
-pip3 install -r requirements.txt --break-system-packages
+pip3 install -r requirements.txt
 ```
 The [Installing Sphinx] documentation explains more install options.
 For macOS, it is recommended to install it using homebrew:
@@ -128,3 +147,17 @@ A list of useful tools to write documentation:
 [Python virtual environments]: https://docs.python.org/3/library/venv.html
 [sphinx-autobuild]: https://pypi.org/project/sphinx-autobuild/
 [Read the Docs]: https://readthedocs.org
+
+
+### Dependency management
+
+Find outdated dependencies using the following command:
+```
+pip list --outdated
+```
+
+Find unused dependencies using the following command:
+```
+pip install deptry
+deptry .
+```

docs/admin/setup/customization.rst

@@ -7,4 +7,5 @@ instead of the TUM defaults:
 * The logo next to the “Artemis” heading on the navbar → ``${artemisRunDirectory}/public/images/logo.png``
 * The favicon → ``${artemisRunDirectory}/logo/favicon.svg``
 * The contact email address in the ``application-{dev,prod}.yml`` configuration file under the key ``info.contact``
+* The operator's name  (e.g. university) and the operator's contact information (administrator email address and name) can be specified in the ``application-{dev,prod}.yml`` configuration file under the keys ``info.operatorName``, ``info.contact`` and ``info.operatorAdminName``. These values are also displayed on the ``/about`` page. The operator's name is required, while the administrator's name is optional. Artemis also uses this information for the :ref:`telemetry` service.
 * The maximal number of plagiarism results stored per plagiarism checks in the ``application-{dev,prod}.yml`` configuration file under the key ``artemis.plagiarism-checks.plagiarism-results-limit``

docs/admin/telemetry.rst

@@ -0,0 +1,37 @@
+.. _telemetry:
+
+Telemetry
+=========
+
+To help to improve Artemis, we collect some data when the application starts.
+This feature can be disabled by setting `telemetry.enabled` in the `application-prod.yml` to `false`.
+When this is set to false, no data is sent to the Artemis maintainer team.
+By setting `telemetry.sendAdminDetails` to false, personal information of the instance's admin (i.e. contact email and name) is excluded from the telemetry data.
+This includes the contact email and the administrator's name.
+
+Artemis collects the following data at the startup of an instance:
+
+* The used Artemis version
+* The contact email address of the admin, which is set in `info.contact`
+* The name of the admin, set in `info.operatorAdminName` (optional)
+* The server's URL
+* The operator's name
+* The used profiles (e.g. Gitlab, Jenkins, LocalVC, Aeolus, ...)
+
+Example configuration in `application-prod.yml`:
+
+.. code-block:: yaml
+
+    artemis:
+        telemetry:
+            enabled: true
+            sendAdminDetails: false
+            destination: telemetry.artemis.cit.tum.de
+
+    info:
+        contact: contactMailAddress@cit.tum.de
+        operatorName: Technical University of Munich
+        operatorAdminName: Stephan Krusche
+
+We collect this data to enhance Artemis by understanding how it is used, ensuring compatibility with different configurations, and providing better support to our users.
+Collecting admin contact information allows us to communicate important updates or address critical issues directly.

docs/dev/guidelines/client.rst

@@ -11,7 +11,24 @@ Some general aspects:
 
 * The Artemis client uses lazy loading to keep the initial bundle size below 2 MB.
 * Code quality and test coverage are important. Try to reuse code and avoid code duplication. Write meaningful tests!
+* Use **standalone components** instead of Angular modules: https://angular.dev/reference/migrations/standalone
+* Use the new ``signals`` to granularly track how and where state is used throughout an application, allowing Angular to optimize rendering updates: https://angular.dev/guide/signals
+* Find out more in the following guide: https://blog.angular-university.io/angular-signal-components/
+* Use the new ``input()`` and ``output()`` decorators instead of ``@Input()`` and ``@Output()``.
 
+    .. code-block:: ts
+
+        // Don't
+        @Input() myInput: string;
+        @Output() myOutput = new EventEmitter<string>();
+
+        // Do
+        myInput = input<string>();
+        myOutput = output<string>();
+
+* Use the new ``inject`` function, because it offers more accurate types and better compatibility with standard decorators, compared to constructor-based injection: https://angular.dev/reference/migrations/inject-function
+* Use the new way of defining queries for ``viewChild()``, ``contentChild()``, ``viewChildren()``, ``contentChildren()``: https://ngxtension.netlify.app/utilities/migrations/queries-migration/
+* Use ``OnPush`` change detection strategy for components whenever possible: https://blog.angular-university.io/onpush-change-detection-how-it-works/
 
 .. WARNING::
     **Never invoke methods from the html template. The automatic change tracking in Angular will kill the application performance!**
@@ -72,7 +89,7 @@ More info about standalone components: https://angular.dev/guide/components/impo
 
 
 
-6. Use strict typing to avoid type errors: Do not use ``any``.
+6. Use strict typing to avoid type errors: **Never** use ``any``.
 
 7. Do not use anonymous data structures.
 
@@ -92,7 +109,7 @@ More info about standalone components: https://angular.dev/guide/components/impo
 4. ``null`` and ``undefined``
 =============================
 
-Use **undefined**. Do not use null.
+Use **undefined**. **Never** use ``null``.
 
 5. General Assumptions
 ======================
@@ -104,6 +121,8 @@ Use **undefined**. Do not use null.
 ============
 
 Use JSDoc style comments for functions, interfaces, enums, and classes.
+Provide extensive documentation inline and using JSDoc to make sure other developers can understand the code and the rationale behind the implementation
+without having to read the code.
 
 7. Strings
 ============

docs/index.rst

@@ -77,6 +77,7 @@ All these exercises are supposed to be run either live in the lecture with insta
    admin/database
    admin/knownIssues
    admin/benchmarking-tool
+   admin/telemetry
 
 
 .. toctree::

docs/requirements.txt

@@ -1,4 +1,4 @@
 Sphinx==7.4.7
 sphinx-rtd-theme==2.0.0
-sphinx-autobuild==2024.04.16
+sphinx-autobuild==2024.4.16
 sphinxcontrib-bibtex==2.6.2