Skip to content

LLM: Generate Docs #749

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Yemaneberhan-Lemma wants to merge 1 commit into
base: main
Choose a base branch
from
Open

LLM: Generate Docs #749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 109 additions & 60 deletions docs/ci_cd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,60 +1,109 @@
# Continuous Integration and Deployment

This GitHub Actions workflow automates testing, code quality checks, and deployment to platform.sh.

## Trigger

The CI workflow is triggered by:

- Push events to the `main` branch.
- Push events creating new tags.
- Pull request events.

## Concurrency Control

The workflow ensures concurrency control, allowing only one workflow run per branch/tag. It cancels in-progress runs if a new run is triggered.

## Jobs

Each job checks out the repository code using [actions/checkout](https://github.com/actions/checkout) and performs caching with [actions/cache](https://github.com/actions/cache) to optimize subsequent runs.

### 1. Drupal Code Quality (`drupal_codequality`)

**Intent:** Ensure Drupal code quality.

**Description:** Uses GrumPHP to perform code quality checks on the Drupal codebase, ensuring adherence to our predefined standards. We use [axelerant/drupal-quality-checker](https://github.com/axelerant/drupal-quality-checker) for local checks, so we apply the same configuration in CI to maintain consistency.

### 2. Frontend Code Quality (`frontend_codequality`)

**Intent:** Ensure frontend code quality.

**Description:** This job runs linting checks on JavaScript and other frontend code to maintain code quality and consistency.

### 3. Drupal Test (`drupal_test`)

**Intent:** Run comprehensive tests on the Drupal site.

**Description:** This job sets up the ddev environment in CI to replicate the local development environment. It performs the following tests:
- **Unit Tests with DTT:** Ensures individual units of code work as expected.
- **PHPStan Checks:** Static analysis to find errors in code without running it.
- **Cypress Tests:** End-to-end testing to ensure functionalities work. Integrated with Percy for Visual Testing.

**Note:**
- We spin up ddev in CI to ensure a consistent environment with our local development setup. This is necessary because we need a site running for Cypress tests and Drupal test traits.
- PHPStan checks are included in this job and not part of the `drupal_codequality` job because it requires all dependencies to be present.

### 4. Deploy (`deploy`)

**Intent:** Deploy code to platform.sh.

**Description:** This job deploys code to platform.sh based on the branch (`main` for production, others for feature environments). It ensures that only code passing the `drupal_codequality` and `drupal_test` jobs is deployed. Dependabot PRs are excluded from deployment.

## References

- [Events that trigger workflows](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)
- [Caching dependencies](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
- [Drupal Quality Checker](https://github.com/axelerant/drupal-quality-checker)
- [Defining outputs for jobs](https://docs.github.com/en/actions/using-jobs/defining-outputs-for-jobs)
- [Storing workflow data as artifacts](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts)
- [Using Secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)
- [Example Workflows](https://github.com/actions/starter-workflows)
# CI/CD Documentation

This document outlines the Continuous Integration and Continuous Delivery (CI/CD) workflows implemented in this project. These workflows are designed to automate testing, code quality checks, and environment management, facilitating a robust and efficient development lifecycle.

## Workflow Overview

This project leverages GitHub Actions for CI/CD. Workflow definitions are located in the `.github/workflows` directory within the repository. Each workflow addresses a specific aspect of the software development lifecycle, from code quality assurance to environment cleanup.

## Workflow Details

### 1. Visual Regression Testing (VR) Workflow

* **File:** `.github/workflows/vr.yml`
* **Purpose:** Executes visual regression tests to detect unintended visual changes in the application. This helps ensure a consistent user interface across deployments.
* **Triggers:**
* `push` events on tags (`*`): Triggers when a new tag is pushed to the repository, typically indicating a release.
* `workflow_dispatch`: Allows manual triggering of the workflow from the GitHub Actions UI. This is useful for on-demand testing.
* `schedule` (cron: `0 0 * * MON`): Runs the workflow every Monday at midnight (UTC). This provides regular visual regression testing.
* **Concurrency:** Prevents concurrent VR test runs using `vr-${{ github.ref }}`. This ensures that tests are executed in isolation and avoids potential conflicts.
* **Job:** `vr_test`
* **Runs On:** `ubuntu-latest` (latest version of Ubuntu runner).
* **Environment Variables:** Configures environment variables required for the test execution.
* `CYPRESS_ADMIN_USERNAME`: Username for the administrative user in the Cypress testing environment.
* `CYPRESS_ADMIN_PASSWORD`: Password for the administrative user in the Cypress testing environment.
* `PERCY_TOKEN`: API token for authenticating with the Percy visual regression testing platform. This is retrieved from GitHub secrets for security.
* **Steps:**
1. **Checkout Code:** Checkouts the repository code using `actions/checkout@v4`, making the project code available to the workflow.
2. **Determine Cache Directories:** This step identifies cache directories for Composer and npm, optimizing dependency management for subsequent runs by storing and retrieving cached dependencies.

### 2. Pull Request Close Workflow

* **File:** `.github/workflows/pr-close.yml`
* **Purpose:** Cleans up Platform.sh environments that were provisioned for pull request testing. This helps to minimize resource usage and avoid unnecessary costs.
* **Triggers:** `pull_request` events with `types: [closed]`: Triggers when a pull request is closed (either merged or closed without merging).
* **Job:** `on-pr-close`
* **Runs On:** `ubuntu-latest`
* **Steps:**
1. **Clean PR Environment:** Utilizes the `axelerant/platformsh-action@v1` action with the `clean-pr-env` parameter. This action automatically removes the Platform.sh environment associated with the closed pull request. The workflow requires the following parameters:
* `project-id`: The Platform.sh project ID. Often configured within the repository settings or workflow file (refer to Axelerant's documentation for specifics)
* `cli-token`: A Platform.sh CLI token with appropriate permissions. This token is securely stored as a GitHub secret (`secrets.PLATFORMSH_CLI_TOKEN`).

### 3. Cypress Tests Workflow

* **File:** `.github/workflows/cypress-tests.yml`
* **Purpose:** Executes end-to-end (E2E) tests using Cypress. These tests simulate user interactions with the application, verifying its functionality and behavior.
* **Triggers:** `schedule` (cron: `0 0 * * 0`): Runs the workflow every Sunday at midnight (UTC). This ensures that E2E tests are performed regularly.
* **Job:** `cypress_tests`
* **Runs On:** `ubuntu-latest`
* **Environment Variables:**
* `CYPRESS_ADMIN_USERNAME`: Username for the administrative user in the Cypress testing environment.
* `CYPRESS_ADMIN_PASSWORD`: Password for the administrative user in the Cypress testing environment.
* **Steps:**
1. **Checkout Code:** Checkouts the repository code.
2. **Setup DDEV:** Sets up DDEV (a local development environment tool) using the `ddev/github-action-setup-ddev@v1` action.
3. **Configure DDEV:** Configures DDEV to include the Platform.sh token using `ddev config global`. This allows DDEV to interact with Platform.sh during testing.
4. **Install Dependencies and Start DDEV:** Installs Composer dependencies using `ddev composer install` and starts the DDEV environment using `ddev`.

### 4. Continuous Integration (CI) Workflow

* **File:** `.github/workflows/ci.yml`
* **Purpose:** Performs code quality checks to ensure that the codebase adheres to defined coding standards and best practices.
* **Triggers:**
* `push` events on the `main` branch and tags (`*`): Triggers when changes are pushed to the main branch or when a tag is created.
* `pull_request`: Triggers when a pull request is opened, updated, or synchronized.
* **Concurrency:** Prevents concurrent CI runs using `${{ github.ref }}`.
* **Jobs:**
* `drupal_codequality`: Performs Drupal-specific code quality checks.
* **Uses:** `hussainweb/drupalqa-action@v2` (a GitHub Action designed for Drupal code quality).
* **PHP Version:** Specifies PHP version 8.2 for the code analysis.
* **GrumPHP Configuration:** Configures code quality checks using GrumPHP, including:
* `phplint`: Checks for PHP syntax errors.
* `yamllint`: Checks for YAML syntax errors and formatting issues.
* `jsonlint`: Checks for JSON syntax errors and formatting issues.
* `phpcs`: Checks for PHP coding standard violations using PHP_CodeSniffer.
* `phpmd`: Performs static analysis of PHP code using PHP Mess Detector.
* `twigcs`: Checks for coding standards violations in Twig templates.
* `frontend_codequality`: Performs frontend code quality checks.
* **Container:** Uses a `node:18` container to provide a Node.js environment for the checks.
* **Steps:**
1. `npm install`: Installs Node.js dependencies.
2. Runs linting processes (details of specific linting tools and configurations should be found within the `package.json` file or related configuration files in the project repository, for example: ESLint, stylelint).

## Secrets

The workflows utilize GitHub secrets for storing sensitive information, enhancing security:

* `PERCY_TOKEN`: API token for authenticating with the Percy visual regression testing platform.
* `PLATFORMSH_CLI_TOKEN`: A Platform.sh CLI token used for interacting with the Platform.sh API. This secret should have the necessary permissions to manage environments.

## Dependencies

The CI/CD workflows rely on several key dependencies:

* **GitHub Actions:** The underlying platform for workflow execution.
* **Community Actions:** Reusable actions from the GitHub Marketplace that simplify common tasks (e.g., `actions/checkout@v4`, `axelerant/platformsh-action@v1`, `hussainweb/drupalqa-action@v2`, `ddev/github-action-setup-ddev@v1`).
* **DDEV:** A local development environment tool used to configure and manage the testing environment within the CI workflows.
* **Platform.sh:** A cloud hosting platform used for environment management, particularly for pull request environments.
* **GrumPHP:** A PHP task runner used for automating code quality checks in Drupal projects.
* **Node.js/npm:** A javascript runtime environment and package manager, both of which are used for Frontend Code Quality Checks.
* **Composer:** A dependency manager for PHP used to managing project dependencies.

## Interactions

The workflows interact with the following services and tools:

* **GitHub:** Provides source code management, workflow execution, and secure secret storage.
* **Platform.sh:** Provides cloud hosting and environment management.
* **Percy:** A visual regression testing platform.
* **DDEV:** A local development environment platform.
Loading
Loading