diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 712915b..5b9f222 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -21,7 +21,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: token: ${{ secrets.gh_pat }} submodules: pwdrecursive diff --git a/docs/00-overview.md b/docs/00-overview.md index 5a670ba..80d60af 100644 --- a/docs/00-overview.md +++ b/docs/00-overview.md @@ -1,3 +1,43 @@ # Overview -TODO: CI/CD infrastructure overview +This repository contains **reusable GitHub Actions workflows** that are used by most of the services and libraries written in different languages across our organization. The actions standardize and streamline the **CI/CD** pipeline by allowing the common build, test and release logic to be a modular and shareable workflow. + +## The Available Reusable Actions + +### 1. build-and-upload.yaml + +This workflow builds and packages the services for a release. The workflow runs on our [self-hosted runner](03-debixbuilder.md) and is triggered on `pull-request` and `release` events. + +The workflow builds the service using `make build`, which is triggered for both events. However, if the event is `release` then we also perform the following steps after building the service: + +- Update the `service.yaml` to include the newest version number from the release +- Then zip up the binary and the `service.yaml` +- Finally, upload the package as a GitHub Release Asset. + +### 2. release.yaml + +This workflow is used to automate the versioning and changelog generation process by using [Release Please](https://github.com/googleapis/release-please). It doesn't run on our [self-hosted runner](03-debixbuilder.md), instead, it uses GitHub's default `ubuntu-latest` runner. + +It is triggered by a `workflow_call` from the repositories, which have a push to `main` as an event trigger themselves. The workflow also requires a `release_please_token` to be passed, which is stored as a Personal Access Token. + +It is responsible for: + +- Analyzing the commit messages to determine the version bump. It always looks at the highest priority commit (feat! → feat → fix) and updates the version by 1 increment, regardless of how many commits there have been. +- It automatically creates a **release pull request** which includes a version bump (e.g., from v0.3.1 to v0.3.2) and an updated `CHANGELOG.md`. + +Some additional details include: + +- The workflow sets `bump-minor-pre-major: true` which indicates that v0.1.0 → v0.2.0 indicates a breaking change, before the release of 1.0.0 +- The release pull request title shows the following pattern: **chore(main): release 1.2.5** + +### 3. test.yaml + +The workflow is responsible for running the tests of the service/library (if implemented) in its own Devcontainer. It also runs using the GitHub's default `ubuntu-latest` runner. + +It is triggered on every push and also requires a `gh_pat` to be passed, which is again stored as a Personal Access Token. The token is used to checkout the repository with submodule support. + +The main steps are: + +- Check out the repository with the submodule support +- Use the [Devcontainer Github Action](https://github.com/devcontainers/ci) to open the container of the associated service/library +- Inside the Devcontainer, run `make test` to run the unit tests (if implemented) \ No newline at end of file diff --git a/docs/01-why.md b/docs/01-why.md new file mode 100644 index 0000000..c21d382 --- /dev/null +++ b/docs/01-why.md @@ -0,0 +1,35 @@ +# Why we need CI/CD + +With the help of CI/CD (Continuous Integration and Continuous Development) we can **automate** the software development lifecycle and also **reduce human error**. All in all, it ensures that all changes are automatically built, tested, and packaged giving us the benefits of shipping reliable code faster. + +Some of the benefits due to using CI/CD: + +- **Automatic testing** +- **Consistent and automated release process** +- **Faster feedback** +- **Saving time** + +## What It Means to Build and Release Software + +Building and releasing software is the process of turning source code into a packaged and versioned product that is ready for distribution or deployment. + +We follow a structured approach to releasing software by using **conventional commits** and the [Release Please](https://github.com/googleapis/release-please) GitHub Action. + +### Conventional Commits + +All commit messages should follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard, which looks like: + +``` +feat: add dependent service +fix: correct service yaml value +chore: update dependencies +``` + +Using this format allows us to **automatically determine the next version number**. + +### Using Release Please + +The following are the steps of how Release Please automates the release process: + +- Scan commit history for conventional commits +- Creates a **release pull request** with a new version number and updated `CHANGELOG.md` diff --git a/docs/02-reusable.md b/docs/02-reusable.md new file mode 100644 index 0000000..dc07fb0 --- /dev/null +++ b/docs/02-reusable.md @@ -0,0 +1,114 @@ +# List of Repos and their build action + +The following is a comprehensive list of repositories and whether they have reusable or specific actions implemented: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RepoBuild and UploadReleaseTest
roverlib-goNo BuildReusableReusable
roverlib-cNo BuildReusableReusable
roverlib-pythonNo BuildReusableReusable
docsIts own action called fetch-and-deploy
roverIts own version of buildReusable
imagingReusableReusableReusable
actuatorReusableReusableReusable
controllerReusableReusableReusable
actuator-testerReusableReusableReusable
energyReusableReusableReusable
remote-controlReusableReusableReusable
transceiverReusableReusableReusable
displayReusableReusableReusable
batteryReusableReusableReusable
distanceReusableReusableReusable
roverlib-c-sharpOld CI/CD configuration (needs to be updated to standard) +
lidarReusableReusableReusable
diff --git a/docs/03-debixbuilder.md b/docs/03-debixbuilder.md new file mode 100644 index 0000000..d872598 --- /dev/null +++ b/docs/03-debixbuilder.md @@ -0,0 +1,3 @@ +# Self-hosted Runner + +We have configured one debix board as a self-hosted Runner for the Build GitHub workflow. We have done this for several reasons. Crucially the most important reasons is to have all the dependencies (such as OpenCV) installed on the device that builds the services. Cloning them on the remote GitHub server would be time consuming. Furthermore, the runner ensures consistency in building the services, meaning that if the service can be built on it, the chances are high that it will build and work on the rover's debix. \ No newline at end of file diff --git a/docs/04-syncdocs.md b/docs/04-syncdocs.md new file mode 100644 index 0000000..a414eb6 --- /dev/null +++ b/docs/04-syncdocs.md @@ -0,0 +1,5 @@ +# Synching the Docs + +Our docs have a synching mechanism that is defined in the `fetch-and-deploy` workflow. It means that the docs look into all the repositories we use and gathers the files in their `docs` directories. Then it shows their documentations on the official [ASE](https://ase.vu.nl/) website under the Framework/Software tab. + +We have designed this in order to keep the documentation all in one place, making it easier for newcomers and maintainers to search up any information they might need regarding a library, service, embedded or the rover repositories. \ No newline at end of file