From 0c782078a0c2c539bac273712e8aa2339aea77fc Mon Sep 17 00:00:00 2001 From: Andreas Resch Date: Sat, 9 Mar 2024 16:00:52 +0100 Subject: [PATCH] =?UTF-8?q?more=20docs=20=F0=9F=94=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/build-and-push.yaml | 4 +- .gitignore | 1 + docs/figures/windfile_structure.pdf | Bin 0 -> 22492 bytes docs/index.rst | 6 + docs/input/index.rst | 171 ++++++++++++++++++++++++++ 5 files changed, 181 insertions(+), 1 deletion(-) create mode 100644 docs/figures/windfile_structure.pdf create mode 100644 docs/input/index.rst diff --git a/.github/workflows/build-and-push.yaml b/.github/workflows/build-and-push.yaml index 1e48f2c8..78f67c16 100644 --- a/.github/workflows/build-and-push.yaml +++ b/.github/workflows/build-and-push.yaml @@ -4,6 +4,8 @@ on: workflow_dispatch: pull_request: push: + tags: + - "v*.*.*" branches: - develop paths-ignore: @@ -87,7 +89,7 @@ jobs: type=raw,value={{date 'YYYYMMDD-hhmmss' tz='Europe/Berlin'}} type=ref,event=pr type=sha - type=raw,value={{steps.compute-tag.outputs.result}} + type=raw,value=${{steps.compute-tag.outputs.result}} type=raw,value=nightly,enable={{is_default_branch}} - name: Build and push uses: docker/build-push-action@v5 diff --git a/.gitignore b/.gitignore index 52ed3bd6..526eb34d 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,7 @@ # Generated files .idea/**/contentModel.xml +.idea/copilot/ # Sensitive or high-churn files .idea/**/dataSources/ diff --git a/docs/figures/windfile_structure.pdf b/docs/figures/windfile_structure.pdf new file mode 100644 index 0000000000000000000000000000000000000000..604a0df111f0da3cf28be55d656a131cbf48edf8 GIT binary patch literal 22492 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 +.. toctree:: + :maxdepth: 3 + :caption: Input definition + + input/index + .. toctree:: :maxdepth: 3 :caption: User Guide diff --git a/docs/input/index.rst b/docs/input/index.rst new file mode 100644 index 00000000..92360d2e --- /dev/null +++ b/docs/input/index.rst @@ -0,0 +1,171 @@ +Input Structure Overview +======================== + +Our input structure, as depicted below, is encapsulated within either a Windfile (highlighted in blue) or an Actionfile (highlighted in green). Designed for extensibility (NFR7), the structure comprises various components explained in the following sections. + +.. figure:: ../figures/windfile_structure.pdf + :width: 100% + :alt: The structure of the input expected by Aeolus. + +Windfiles +--------- + +Windfiles serve as the outermost layer, describing a CI job. They encompass essential information such as job actions, required repositories, and metadata like optional container images, callback URLs, or repository checkout credentials. + +Actionfiles +------------ + +While Windfiles provide a complete configuration for multiple targets, Actionfiles partially define a job. They facilitate code reuse by importing externally implemented and open-source actions, akin to GitHub Actions' concept (`GitHub Actions `_). + +Action and Step +--------------- + +The smallest but crucial part of our input is the step or action. Actions, further specialized into steps, define the script executed in the target system. Two key terms distinguish Windfiles and Actionfiles: Steps are specialized actions not directly part of a Windfile, imported and converted into actions during code generation. + +Script Action +^^^^^^^^^^^^^ + +The simplest action, a *Script Action*, is directly defined in a Windfile or Actionfile. It contains a shell script for execution in the target system. + +.. code-block:: yaml + :caption: Example of a Script Action in Aeolus. + :name: lst-script-action + + - name: echo-action + script: | + echo "I can be used to write inlined code." + +File Action +^^^^^^^^^^^ + +A *File Action* defines a file containing shell code, suitable for longer, more complex scripts. The script content is integrated into the final result and converted to a Script Action. + +.. code-block:: yaml + :caption: Example of a File Action in Aeolus. + :name: lst-file-action + + - name: complicated-action + file: overly-long-action.sh + +Platform Action +^^^^^^^^^^^^^^^ + +*Platform Actions* serve two purposes: preparing the target CI system for other actions and providing platform-specific actions for specific targets. + +- The first type executes Python code to dynamically prepare the CI system, using the target's interfaces, like API calls. + +.. code-block:: yaml + :caption: Example of a Platform Action using a Python Script in Aeolus. + :name: lst-platform-action-python + + - name: install plugin + platform: bamboo + code: install-plugin.py + function: run + +- The second type caters to target-specific actions. These actions are excluded for non-matching targets. + +.. code-block:: yaml + :caption: Example of a Platform Action in Aeolus. + :name: lst-platform-action + + - name: junit parser + parameters: + test_results: "**/tests/test/*.xml" + platform: bamboo + kind: junit + runAlways: true + +Template Action +^^^^^^^^^^^^^^^ + +*Template Actions* utilize Actionfiles within Windfiles, facilitating code sharing and reuse. + +.. code-block:: yaml + :caption: Example of a Template Action in Aeolus. + :name: lst-template-action + + - name: open source action + use: https://github.com/reschandreas/example-action.git + parameters: + WHO_TO_GREET: "thesis readers." + +Results +------- + +In Aeolus, the term "results" replaces "artifacts." Results, essential for assessing submissions, represent files indicating submission quality and compliance with the problem statement. + +.. code-block:: yaml + :caption: Example of results specified for an action in Aeolus. + :name: lst-results + + results: + - name: junit_**/tests/test/*.xml + path: "**/tests/test/*.xml" + type: junit + +Docker Configuration +-------------------- + +To support multiple operating systems and other environments, Aeolus relies on containers. +The Docker configuration, as shown in our input diagram and exemplified below, allows specifying image, tag, volumes, and parameters. + +.. code-block:: yaml + :caption: Example of a Docker configuration in a Windfile. + :name: lst-docker-config + + docker: + image: ls1tum/artemis-maven-template + tag: java17-20 + parameters: + - --cpus=2 + +Environment Variables +---------------------- + +All action types can accept environment variables as input and script generalization. Template actions benefit from defining a set of environment variables for user customization. + +Parameters +---------- + +Differentiating between parameters and environment variables, parameters are handled differently across target systems. An example in :ref:`lst-template-action` demonstrates parameter usage, allowing external actions to define and override parameter values. + +Repositories +------------ + +A CI job in Aeolus processes exercise submissions from multiple repositories. The input definition supports a list of repositories checked out during execution. + +.. code-block:: yaml + :caption: Example of a repository in a Windfile. + :name: lst-repository + + repositories: + aeolus: + url: https://github.com/ls1intum/Aeolus.git + branch: develop + path: repository + +Targets +------- + +Actions can possess the property "targets," specifying platforms where defined actions are needed. This property helps execute scripts on certain platforms while excluding them from others. + +Lifecycle +--------- + +Aeolus supports dynamic action skipping during different exercise stages. Five stages are identified, and an action can be skipped during specific stages or all stages. + +- ``preparation``: Instructor prepares exercise. +- ``working_time``: Students actively work on the exercise. +- ``post_deadline``: Working time ends; no more submissions allowed. +- ``evaluation``: Instructor evaluates submissions. +- ``all``: Action is skipped in all exercise stages. + +.. code-block:: yaml + :caption: Example of a skipped action during exercise preparation. + :name: lst-skipped-action + + - name: echo-action + script: echo "I will be skipped during preparation." + excludeDuring: + - preparation