How jonathanlinat/quake-leveldesign-starterkit works
Project type and purpose
• This is a “starter kit” that consolidates multiple specialized tools and resources for creating maps for Quake and similar engines.
• It leverages a wide range of GitHub Actions workflows to continuously build (for multiple platforms), package (pack/unpack artifacts), and release updates to users.
File structure
• The top-level directories (especially the .github folder) indicate that the core of this project is its CI/CD pipelines.
• Under .github/actions you have a _shared folder containing common helper actions (e.g., downloading artifacts, setting commit details, installing dependencies like Qt, etc.). These are used by specialized workflows.
• There are separate directories inside .github/actions for “continuous-building”, “continuous-packing”, and “continuous-releasing” – each one having further subfolders for individual tools (e.g., ericw-tools, goldutil, ironwail, etc.). Each tool supports both Linux and Windows builds.
• The workflows in .github/workflows tie the process together by triggering the respective actions.
README for additional insights
• The README clearly outlines the suite of applications and tools that QLDSK consolidates. It also provides links to external resources and documentation, emphasizing that the project not only builds the tools but also integrates extra assets (textures, palettes, map sources).
• It explains that this kit aims to simplify the map design process, which in turn requires a well-organized build and release pipeline.
a. Main Components:
• Source Code Repository: Represents the overall repository containing the CI/CD definitions.
• GitHub Actions Workflows: Three main workflows:
▪ Continuous Building – managing compilation and artifact generation for each tool (with subcomponents for Linux and Windows for each tool).
▪ Continuous Packing – handling artifact download and repackaging steps.
▪ Continuous Releasing – packaging the final releases.
• Shared Actions: A collection of reusable actions (found in .github/actions/_shared) that support all the workflows.
• External Components & Tools: Representations of the external level design applications (TrenchBroom, ericw-tools, Ironwail, etc.) and extras (textures, palettes, map sources) that the kit consolidates.
• External Integration Points: Links to the documentation wiki, Discord support channels, and GitHub Releases.
b. Relationships and interactions:
• Initially, code commits trigger specific GitHub workflow files (.github/workflows/*.yml).
• The Continuous Building component uses shared actions for environment setup and artifact management to build binaries on both Linux and Windows.
• The output binary artifacts proceed to the Continuous Packing component, which downloads and processes these artifacts.
• Finally, the Continuous Releasing component collects the packed artifacts and triggers a release, making them available for download.
• External integrations (documentation, Discord) connect users back to supporting information and community channels.
c. Architectural patterns/design principles:
• Modularization: The repository design intentionally modularizes shared actions and separates workflows by function (build, pack, release).
• Platform-Specific Pipelines: Clearly distinct paths for Linux and Windows builds for each supported tool.
• Continuous Integration/Continuous Deployment (CI/CD): Extensive use of GitHub Actions as the orchestration engine to ensure smooth and automated processes.
d. Technologies and frameworks:
• GitHub Actions as the CI/CD automation platform.
• YAML configuration files for defining workflows and actions.
• Build tools/scripts referenced implicitly in the actions (e.g., MSVC setup, Qt installation).
• Integration with external repositories and tools (e.g., external source ports, third-party packages).
Instructing the principal software engineer to include these elements
– Repository (and within it, the .github folder)
– Shared Actions (listing some key actions like artifact management, environment setup)
– Continuous Packing and Continuous Releasing
– External tools/resources and integration links.
– Triggering of workflows (commit → workflows)
– Flow of artifacts from building to packing to releasing.
– Connections between the CI/CD pipeline and external delivery endpoints (like GitHub Releases and the documentation wiki).