diff --git a/README.md b/README.md index 1a662ef..684da4e 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,50 @@ # SPT Build Project - CI/CD Overview -This document provides an overview of the Continuous Integration and Continuous Deployment (CI/CD) implemented for the `SPT-AKI` project. This framework is responsible for automating the compilation, building, and deployment phases across three critical repositories: [SPT-AKI/Server](https://dev.sp-tarkov.com/SPT-AKI/Server), [SPT-AKI/Modules](https://dev.sp-tarkov.com/SPT-AKI/Modules), and [SPT-AKI/Launcher](https://dev.sp-tarkov.com/SPT-AKI/Launcher). The process is orchestrated using Gitea Actions. +This guide outlines the Continuous Integration (CI) and Continuous Deployment (CD) setup for the SPT-AKI project. It automates and streamlines processes across three key repositories: [SPT-AKI/Server](https://dev.sp-tarkov.com/SPT-AKI/Server), [SPT-AKI/Modules](https://dev.sp-tarkov.com/SPT-AKI/Modules), and [SPT-AKI/Launcher](https://dev.sp-tarkov.com/SPT-AKI/Launcher), utilizing Gitea Actions for efficient operations. -### CI/CD Build Process +**Why Gitea Actions?** Gitea Actions integrates directly with our workflow, automating the compile, build, and deployment phases. This ensures every update is processed accurately and deployed swiftly, minimizing manual effort and error potential. -This repository initiates the CI/CD build process by performing the following actions: +The following sections detail our CI/CD pipeline, highlighting how each update moves from development through to deployment, ensuring consistency and reliability in the build process. -1. Verification of the existence of the specified tag across the three project repositories. -1. Cloning of the repositories at the specified tagged commits. -1. Compilation and building of each project according to predefined specifications. -1. Aggregation and compression of the build artifacts into a singular release file. -1. Distribution of the release file to designated web-accessible storage locations. -1. Dispatching notifications regarding the release to multiple sources. +## Understanding the CI/CD Pipeline + +The CI/CD pipeline of the SPT-AKI project is engineered for tag-based release builds, navigating the complexity of synchronizing three distinct repositories. The pipeline operates through several key stages: + +1. **Tag Verification**: Confirms the presence of a specific tag across all three project repositories. +2. **Repository Cloning**: Retrieves the repositories at their respective tagged states, ensuring that the build reflects the exact version intended for release. +3. **Builds**: Build each individual project, ensuring that all builds meet the required standards for integration. +4. **Aggregation**: Consolidates and compresses build artifacts into a single release package, preparing it for distribution. +5. **Distribution**: Uploads the release package to online storage locations, making it available for download. +6. **Notifications**: Sends automated alerts about the new release through multiple channels to inform project maintainers and users of the new build. + +## Tagging Strategy and Build Types + +The CI/CD pipeline of the SPT-AKI project uses specific tagging conventions to trigger different types of builds. This allows for a more nuanced approach to building and deploying code. Below is an explanation of the build types recognized by the workflow and the tagging required for each. + +### Release Builds +- **Tagging Convention**: Semantic versioning (e.g., `v1.2.3` or `1.2.3`). +- **Description**: `release` builds are stable versions intended for distribution. They are tested, have limited support, and contain less debugging printed to the server console. +- **Use Case**: Suitable for production releases, signifying major updates or critical fixes. + +### Bleeding Builds +- **Tagging Convention**: Semantic versioning followed by a `-BE`. (e.g., `1.2.3-BE`). These can also incldue a string after the `-BE` to signify a specific build identifier (e.g., `1.2.3-BE-Identifier`) +- **Description**: `bleeding` builds are cutting-edge versions that may include experimental updates. They're less stable than `release` builds but offer a glimpse into the latest developments. +- **Use Case**: For developers and testers looking for the latest features and willing to accept instability. + +### BleedingMods Builds +- **Tagging Convention**: Follows the same format as `bleeding` builds, except the tag is `-BEM` (e.g., `1.2.3-BEM` or `1.2.3-BEM-Identifier`). +- **Description**: Similar to `bleeding` but with modifications enabled, `bleedingmods` builds include the latest changes so that mod developers can test and experiment with their mods. +- **Use Case**: Targeted at mod developers and users interested in testing the cutting edge of mod development. + +### Debug Builds +- **Tagging Convention**: Any tag that does not match the above conventions. +- **Description**: `debug` builds are intended for internal use, featuring extensive logging and debugging information. Stability is not even an afterthought. +- **Use Case**: Development and troubleshooting, where detailed logs and error messages are essential for fixing bugs. + +### Nightly Builds +- **Tagging Convention**: Scheduled triggers, not tag-based. +- **Description**: `nightly` builds are created automatically based on a schedule, usually daily. These builds reflect the most current development progress and are useful for continuous testing. Not stable. Not supported. +- **Use Case**: Ongoing testing and early detection of bugs or integration issues in the development phase. ## Project Repositories Configuration @@ -19,12 +52,12 @@ Each of the three main repositories (Modules, Server, Launcher) are equipped wit 1. Cloning of *this* Build repository. 1. Creation and checkout of a dedicated `trigger` branch within *this* Build repository. -1. Committing of a `.gitea/trigger` file into the `trigger` branch, embedding the tag name for traceability. +1. Committing a `.gitea/trigger` file into the `trigger` branch, embedding the tag name used to start the build process. 1. Forceful push of the `trigger` branch back to *this* origin `Build` repository to trigger the build process. ## Module Build Requirements -The build process for the Modules project necessitates access to a secured private repository. A link to this repository is saved as a Gitea environment secret, named `MODULE_DOMAIN`. The build process will fail if this secret is not defined. +The build process for the Modules project necessitates access to a secured private repository. A link to this repository is saved as a Gitea environment secret, named `MODULE_DOMAIN`. The build process will fail if this secret is not defined and the modules can not be downloaded. ## Building the Docker Images @@ -39,5 +72,3 @@ docker push refringe/spt-build-node --all-tags docker build -t refringe/spt-build-dotnet:1.0.1 -t refringe/spt-build-dotnet:latest -f Dockerfile.dotnet . docker push refringe/spt-build-dotnet --all-tags ``` - -♥️