For the startup instructions, read readme in the src folder

Link to the Github repository: Link

Advanced Software Architecture and Analysis Portfolio Template

• Introduction
  • .github
    • CI/CD Workflow
    • Hand in Workflow
  • .vscode
  • Report
  • Src
• Compiling Latex
  • Option 1: LaTeX Workshop + TeX Live
    • Extension
    • Link to download TeX Live
  • Option 2: Trigger Task on Save + Docker
    • Compilation of latex on save
  • Option 3: Overleaf
• Recommended VSCode Extension

Introduction

This repository serves as a template for students of Advanced Software Engineering to structure their portfolio project.

Below is the detailed overview of the repository structure:

.
├── .github/
│   └── workflows/
│       ├── ci-cd.yml
│       └── handin.yml
├── .vscode/
│   ├── settings.json
│   └── tasks.json
├── Report/
│   ├── GroupTemplate/
│   └── ReflectionsTemplate/
├── Src/
└── .gitignore

.github

This folder contains template workflows designed for CI/CD processes and for generating the final submission artifacts.

CI/CD Workflow

The CI/CD workflow is split into several jobs:

• Clone repository: Clones the repository, creates an artifact from it, and then uploads this artifact, ensuring consistency across all jobs.
• Code analysis: Utilize this job for linting or any other static code analysis tools you'd like to incorporate.
• Build application: Compile the source code. After compiling, the artifact is uploaded for easy accessibility, aiding in debugging and local testing.
• Test application: Run tests that require the code to be compiled. This step downloads the compiled artifact created in the previous step.
• Build and push image: Builds an image using a specified DockerFile and pushes the image to the GitHub container registry specific to the repository owner.
• Deploy application: Can be used to deploy the image(s) generated during the workflow onto your virtual machines.

Hand in Workflow

The hand-in workflow includes some of the jobs from the CI/CD workflow and some additional ones:

• Compile latex groupReport: This job compiles the latex source files for the group report and upload the output as an artifact.
• Compile latex groupReport: This job compiles the latex source files for the reflections document and upload the output as an artifact.
• Upload hand-in artifacts: This job creates a zip file containing the Group Report, the Reflections Document, the source code, and any build artifacts. The zip can be downloaded by navigating to Repository > Actions > The completed hand-in workflow as shown in the image below.

Report

This directory contains the latex source files essential for the group report and the reflections document.

The directory latexUtils contains scripts for compiling LaTeX locally using docker, you do not need to change anything in these files, but you are welcome to do so if you want to.

Src

This folder is intended for organizing and storing all your source code. You decide on the structure but please keep everything source code related inside ./src. You are allowed to have your DockerFiles at root level for build context reasons, as the example DockerFile provided.

Compiling Latex

You can compile latex source files to PDF locally. Multiple options are available; choose the one you prefer.

Option 1: LaTeX Workshop Extension + TeX Live

For this option, you'll need the VSCode extension called LaTeX Workshop and the LaTeX Distribution named TeX Live.

While TeX Live does require 6GB! of space, it is a comprehensive collection of nearly all LaTeX packages, it is very user-friendly when paired with LaTeX Workshop.

Extension

Link to download TeX Live

TeX Live Official Download

Option 2: Trigger Task on Save Extension + Docker

This option requires Docker to be installed and running.

Here's how it works:

Inside the report directory, there's a docker-compose-latex.yml file.

• This docker-compose file will create bind volumes for the GroupTemplate and ReflectionsTemplate folders.
• A docker container will start, compile the latex source files, and then exit. The initial process might be a little time-consuming as it needs to create the image. However, afterwards compilations are faster.

To manually run the docker-compose-latex.yml and compile both latex documents, use the command:

• docker compose -f report/docker-compose-latex.yml up

To only compile a specific latex document i.e GroupReport or Reflections use these commands:

• docker compose -f report/docker-compose-latex.yml run latex reflection
• docker compose -f report/docker-compose-latex.yml run latex groupreport

Trigger Task on Save Extension

If you're using VSCode, you can set up your latex files to compile upon saving. For this, download the Trigger Task on Save extension.

This extension will trigger tasks defined in .vscode/tasks.json every time you save a .tex file. The task will execute the docker compose -f report/docker-compose-latex.yml run latex command with a parameter, depending on the .tex file you are working on.

Option 3: Overleaf

You are free to import the latex source files into Overleaf.

• If you use this method, you could export the source files from overleaf when done with the report and reflections document.
• By placing the source files into their respective folders repot/GroupTemplate and report/ReflectionsTemplate you can still take advantage of the handin workflow when creating your final hand in artifact.

Recommended VSCode Extension

GitHub Actions

• GitHub workflow documentation
• Auto completion
• Overview of workflow runs directly from VSCode