Skip to content

Commit c87a22a

Browse files
author
Axelerant IDP
committed
Initial commit from IDP scaffolder plugin
1 parent 3e1f943 commit c87a22a

11 files changed

+1021
-0
lines changed

‎docs/automated-testing.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Testing and Quality Assurance
2+
3+
This document outlines the testing strategies and configurations employed in this project. It covers code quality checks, visual regression testing, and end-to-end testing, providing a comprehensive approach to maintaining a high-quality codebase and a stable user experience.
4+
5+
## Code Quality
6+
7+
The project uses a combination of tools to ensure code quality and adherence to coding standards. Two CI/CD pipelines are configured: one in GitLab and one in GitHub Actions.
8+
9+
### GitLab CI/CD (`.gitlab-ci.yml`)
10+
11+
The `.gitlab-ci.yml` file defines a pipeline stage named `lint` that executes code quality checks using the `hussainweb/drupalqa:php7.4` Docker image.
12+
13+
**Configuration:**
14+
15+
* **Image:** `hussainweb/drupalqa:php7.4`
16+
* **Scope:** Checks custom modules located in the `web/modules/custom/` directory.
17+
* **Checks performed:**
18+
* `composer validate`
19+
* `phplint`
20+
* `phpcs`
21+
* `phpmd`
22+
* **Branches:** Runs on `master`, `theme`, `tags`, and `merge_requests` branches.
23+
* **Exclusions:** Scheduled pipelines are excluded.
24+
25+
This ensures all custom code adheres to the Drupal coding standards.
26+
27+
### GitHub Actions (`ci.yml`)
28+
29+
The `ci.yml` GitHub Actions workflow performs code quality checks on every push to the `main` branch or tags, and on every pull request.
30+
31+
**Configuration:**
32+
33+
* **Action:** `hussainweb/drupalqa-action@v2`
34+
* **Checks Performed:**
35+
* `composer validate`
36+
* `phplint`
37+
* `yamllint`
38+
* `jsonlint`
39+
* `phpcs`
40+
* `phpmd`
41+
* `twigcs`
42+
43+
A separate job `frontend_codequality` runs code quality checks specifically for frontend code using Node.js. This job typically runs linters and formatters to ensure a consistent frontend codebase in Javascript, Typescript, CSS and SCSS.
44+
45+
## Visual Regression Testing
46+
47+
Visual regression testing is implemented to detect unintended changes in the user interface. The tests are performed through a GitHub Actions workflow.
48+
49+
### GitHub Actions (`vr.yml`)
50+
51+
The `vr.yml` GitHub Actions workflow is responsible for visual regression testing.
52+
53+
**Configuration:**
54+
55+
* **Trigger:** Runs on tags, manually triggered workflows, and a scheduled cron job.
56+
* **Secrets:** Utilizes `PERCY_TOKEN` for authentication with the Percy visual testing platform.
57+
* **Steps:**
58+
1. Checks out the repository code.
59+
2. Sets up caching for Composer and npm dependencies to improve workflow speed.
60+
3. Runs the configured visual regression tests specific to your testing setup.
61+
62+
**Purpose:** This workflow automatically detects visual changes in the UI and helps prevent regressions from being deployed. Remember to review Percy's reports to confirm any changes made.
63+
64+
## End-to-End Testing
65+
66+
End-to-end (E2E) tests are executed using Cypress to ensure the application functions correctly from a user's perspective. The tests are configured via a GitHub Actions workflow that runs on a schedule and utilizes environment variables for configuration.
67+
68+
### GitHub Actions (`cypress-tests.yml`)
69+
70+
The `cypress-tests.yml` GitHub Actions workflow defines end-to-end tests using Cypress.
71+
72+
**Configuration:**
73+
74+
* **Schedule:** Runs weekly (every Sunday).
75+
* **Steps:**
76+
1. Sets up and starts DDEV.
77+
2. Configures the Platform.sh token to access the hosting platform.
78+
3. Installs dependencies with Composer.
79+
4. Uses Cypress to run tests located in the `tests/cypress` directory.
80+
* **Environment Variables:**
81+
* `CYPRESS_ADMIN_USERNAME`: Username for the administrative user in Cypress tests.
82+
* `CYPRESS_ADMIN_PASSWORD`: Password for the administrative user in Cypress tests.
83+
84+
**Notes:**
85+
86+
* Ensure that DDEV is properly configured and running before executing the tests locally. Make sure the `.env` and `.ddev` configurations are up-to-date with correct database, hostname, and user settings.
87+
* Update the `tests/cypress` directory with the appropriate E2E tests for your application.
88+
* Ensure necessary environment variables (e.g. `CYPRESS_ADMIN_USERNAME`, `CYPRESS_ADMIN_PASSWORD`) are correctly set in the GitHub repository settings.
89+
90+
## Platform.sh Environment Management
91+
92+
The project utilizes Platform.sh for hosting, and specific workflows are set up to manage Platform.sh environments.
93+
94+
### GitHub Actions (`pr-close.yml`)
95+
96+
The `pr-close.yml` GitHub Actions workflow automates the cleanup of Platform.sh environments when a pull request is closed.
97+
98+
**Configuration:**
99+
100+
* **Action:** `axelerant/platformsh-action@v1`
101+
* **Action Type:** `clean-pr-env`
102+
* **Secrets:**
103+
* `PLATFORMSH_CLI_TOKEN`: Token for authenticating with the Platform.sh CLI.
104+
* **Variables:**
105+
* `project-id`: `brbqplxd7ycq6` - The Platform.sh project ID.
106+
107+
**Purpose:** This workflow ensures that Platform.sh environments created for pull requests are automatically removed when the pull request is closed, minimizing resource consumption and maintaining a clean hosting environment.

‎docs/ci-cd.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# CI/CD Documentation
2+
3+
This documentation outlines the Continuous Integration and Continuous Delivery (CI/CD) workflows defined within the project, focusing on automated testing, code quality checks, and environment management. The project leverages GitHub Actions for its CI/CD pipeline.
4+
5+
## Workflow Overview
6+
7+
The following workflows are implemented:
8+
9+
* **CI (Continuous Integration):** Validates code quality on every push to the `main` branch and on all pull requests.
10+
* **VR (Visual Regression):** Executes visual regression tests upon pushing tags, manual triggering, and scheduled runs.
11+
* **Cypress Tests:** Runs end-to-end tests to ensure application functionality; scheduled to run every Sunday.
12+
* **Clean Platform.sh env on PR Close:** Manages Platform.sh environments by cleaning up environments associated with closed pull requests.
13+
14+
## Workflow Details
15+
16+
### CI Workflow (`ci.yml`)
17+
18+
* **File:** [.github/workflows/ci.yml](/tmp/59acfa47-f4d9-4bc1-b589-a6f5e02215af/repo-dir/.github/workflows/ci.yml)
19+
20+
This workflow performs Drupal and frontend code quality checks.
21+
22+
* **Triggers:**
23+
* `push` events on the `main` branch and on tags.
24+
* `pull_request` events.
25+
26+
* **Jobs:**
27+
* `drupal_codequality`:
28+
* Uses the `hussainweb/drupalqa-action@v2` action.
29+
* Performs code quality checks using GrumPHP tasks, including:
30+
* phplint
31+
* yamllint
32+
* jsonlint
33+
* phpcs
34+
* phpmd
35+
* twigcs
36+
* PHP version used: 8.2.
37+
* `frontend_codequality`:
38+
* Uses a Node.js 20 container.
39+
* Executes frontend static code analysis.
40+
41+
### VR Workflow (`vr.yml`)
42+
43+
* **File:** [.github/workflows/vr.yml](/tmp/59acfa47-f4d9-4bc1-b589-a6f5e02215af/repo-dir/.github/workflows/vr.yml)
44+
45+
This workflow executes visual regression tests.
46+
47+
* **Triggers:**
48+
* `push` events on tags.
49+
* `workflow_dispatch` for manual runs.
50+
* Scheduled cron job: runs every Monday.
51+
52+
* **Concurrency:** Ensures only one VR test runs at a time for each branch, canceling any in-progress runs.
53+
54+
* **Jobs:**
55+
* `vr_test`:
56+
* Checks out the repository code.
57+
* Sets up cache directories for Composer and npm.
58+
* Executes visual regression tests using Percy.
59+
* Uses the following environment variables:
60+
* `CYPRESS_ADMIN_USERNAME`
61+
* `CYPRESS_ADMIN_PASSWORD`
62+
* `PERCY_TOKEN`
63+
64+
### Cypress Tests Workflow (`cypress-tests.yml`)
65+
66+
* **File:** [.github/workflows/cypress-tests.yml](/tmp/59acfa47-f4d9-4bc1-b589-a6f5e02215af/repo-dir/.github/workflows/cypress-tests.yml)
67+
68+
This workflow runs Cypress end-to-end tests.
69+
70+
* **Triggers:**
71+
72+
* Scheduled to run every Sunday (`cron: "0 0 * * 0"`).
73+
74+
* **Jobs:**
75+
* `cypress_tests`:
76+
* Checks out the repository code.
77+
* Sets up DDEV using the `ddev/github-action-setup-ddev@v1` action.
78+
* Configures the Platform.sh token.
79+
* Installs dependencies using Composer and npm.
80+
* Runs the Cypress tests.
81+
* Uses the following environment variables:
82+
* `CYPRESS_ADMIN_USERNAME`
83+
* `CYPRESS_ADMIN_PASSWORD`
84+
* Relies on the `PLATFORMSH_CLI_TOKEN` secret.
85+
86+
### Clean Platform.sh env on PR Close Workflow (`pr-close.yml`)
87+
88+
* **File:** [.github/workflows/pr-close.yml](/tmp/59acfa47-f4d9-4bc1-b589-a6f5e02215af/repo-dir/.github/workflows/pr-close.yml)
89+
90+
This workflow automates the cleanup of Platform.sh environments when a pull request is closed.
91+
92+
* **Triggers:**
93+
* `pull_request` events with the `closed` type.
94+
95+
* **Jobs:**
96+
* `on-pr-close`:
97+
* Uses the `axelerant/platformsh-action@v1` action with the `clean-pr-env` action to remove the Platform.sh environment.
98+
* Requires `PLATFORMSH_CLI_TOKEN` as a secret.
99+
* Uses `"project-id": "brbqplxd7ycq6"`.
100+
101+
## Dependencies and Secrets
102+
103+
The workflows rely on the following dependencies and secrets:
104+
105+
* **Actions:**
106+
* `actions/checkout@v4`
107+
* `hussainweb/drupalqa-action@v2`
108+
* `ddev/github-action-setup-ddev@v1`
109+
* `axelerant/platformsh-action@v1`
110+
111+
* **Secrets:**
112+
* `PERCY_TOKEN`
113+
* `PLATFORMSH_CLI_TOKEN`
114+
115+
* **Environment Variables:**
116+
* `CYPRESS_ADMIN_USERNAME`
117+
* `CYPRESS_ADMIN_PASSWORD`

‎docs/content-structure.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
```markdown
2+
# Project Content Structure Documentation
3+
4+
This document outlines the content structure of the Drupal project, focusing on content types, vocabularies, views, user roles, and other key configurations that define how content is created, managed, and displayed. This information is intended to help developers quickly understand and navigate the project's content architecture.
5+
6+
## Content Types
7+
8+
Content types define the structure and fields for different kinds of content within the application.
9+
10+
* **Code Contribution:** Used to capture various code contributions, such as patches or modules.
11+
12+
* **Fields:**
13+
* `field_code_contrib_project`: Project association (Taxonomy: Project).
14+
* `field_contribution_technology`: Technology used (Taxonomy: Technology).
15+
* `field_code_contrib_issue_link`: Link to the related issue.
16+
* `field_code_contrib_patches_count`: Number of patches included in the contribution.
17+
* `field_code_contrib_files_count`: Number of files included in the contribution.
18+
* **Configuration File:** `/config/sync/node.type.code_contribution.yml`
19+
20+
* **Non Code Contribution:** Used to capture contributions that do not involve coding.
21+
22+
* **Fields:**
23+
* `field_non_code_contribution_type`: Type of contribution (Taxonomy: Contribution Type).
24+
* `field_non_code_contrib_profile`: Profile of the contributor.
25+
* `field_non_code_contrib_credit`: Credit given for the contribution.
26+
* **Configuration File:** `/config/sync/node.type.non_code_contribution.yml`
27+
28+
* **Issue:** Used for creating new issues, bugs, tasks, or feature requests, and linking them to code contributions.
29+
30+
* **Fields:**
31+
* `field_issue_link`: Link to the related issue.
32+
* **Configuration File:** `/config/sync/node.type.issue.yml`
33+
34+
* **Event Contribution:** Used for capturing contributions made during events.
35+
36+
* **Fields:**
37+
* `field_event_contribution_type`: Type of event contribution (Taxonomy: Event Contribution Type).
38+
* `field_event_contribution_link`: Link to the related event.
39+
* **Configuration File:** `/config/sync/node.type.event_contribution.yml`
40+
41+
* **Event:** Used to create event records that are referred to in Event Contribution content.
42+
43+
* **Fields:**
44+
* `field_event_dates`: Dates of the event.
45+
* `field_event_address`: Address of the event venue.
46+
* `field_event_location`: Location of the event.
47+
* `field_event_additional_links`: Additional links related to the event.
48+
* **Configuration File:** `/config/sync/node.type.event.yml`
49+
50+
* **Page:** Used for static content such as "About us" pages.
51+
52+
* **Fields:**
53+
* `body`: Main content of the page.
54+
* **Configuration File:** `/config/sync/node.type.page.yml`
55+
56+
## Vocabularies
57+
58+
Taxonomy vocabularies are used to categorize and classify content.
59+
60+
* **Technology:** Stores technologies used in contributions.
61+
* **Configuration File:** `/config/sync/taxonomy.vocabulary.technology.yml`
62+
* **Project:** Stores projects for community contributions.
63+
* **Configuration File:** `/config/sync/taxonomy.vocabulary.project.yml`
64+
* **Event Type:** Stores event types, such as DrupalCamp.
65+
* **Configuration File:** `/config/sync/taxonomy.vocabulary.event_type.yml`
66+
* **Event Contribution Type:** Stores event contribution types, such as session or volunteering.
67+
* **Configuration File:** `/config/sync/taxonomy.vocabulary.event_contribution_type.yml`
68+
* **Contribution Type:** Stores contribution types, such as submitting a patch.
69+
* **Configuration File:** `/config/sync/taxonomy.vocabulary.contribution_type.yml`
70+
* **Tags:** Used to group similar articles into categories.
71+
* **Configuration File:** `/config/sync/taxonomy.vocabulary.tags.yml`
72+
73+
## Views
74+
75+
Views are used to display content lists and blocks, allowing for dynamic and customizable content presentation.
76+
77+
* **Frontpage:** Displays content promoted to the front page.
78+
* **Configuration File:** `/config/sync/views.view.frontpage.yml`
79+
* **Content:** Provides an administrative interface to find and manage content.
80+
* **Configuration File:** `/config/sync/views.view.content.yml`
81+
* **Recent content:** Displays recently created content.
82+
* **Configuration File:** `/config/sync/views.view.content_recent.yml`
83+
* **Files:** Provides an administrative interface to find and manage files.
84+
* **Configuration File:** `/config/sync/views.view.files.yml`
85+
* **Patches:** Lists available patches.
86+
* **Configuration File:** `/config/sync/views.view.patches.yml`
87+
* **Glossary:** Displays all content, grouped by the first letter of the title.
88+
* **Configuration File:** `/config/sync/views.view.glossary.yml`
89+
* **Who's online block:** Shows the usernames of the most recently active users and the total number of active users.
90+
* **Configuration File:** `/config/sync/views.view.who_s_online.yml`
91+
* **People:** Provides an administrative interface to find and manage user accounts.
92+
* **Configuration File:** `/config/sync/views.view.user_admin_people.yml`
93+
* **Who's new:** Shows a list of the newest user accounts on the site.
94+
* **Configuration File:** `/config/sync/views.view.who_s_new.yml`
95+
* **All Contributions:** Lists all contributions across all types.
96+
* **Configuration File:** `/config/sync/views.view.all_contributions.yml`
97+
* **Non code contributions:** Lists non-code contributions.
98+
* **Configuration File:** `/config/sync/views.view.non_code_contributions.yml`
99+
* **Code contributions:** Lists code contributions.
100+
* **Configuration File:** `/config/sync/views.view.code_contributions.yml`
101+
* **Event Contributions:** Lists event contributions.
102+
* **Configuration File:** `/config/sync/views.view.event_contributions.yml`
103+
* **Patches on issues:** Lists patches associated with specific issues.
104+
* **Configuration File:** `/config/sync/views.view.patches_on_issues.yml`
105+
* **Taxonomy term:** Displays content belonging to a specific taxonomy term.
106+
* **Configuration File:** `/config/sync/views.view.taxonomy_term.yml`
107+
* **Content blocks:** Provides an administrative interface to find and manage custom blocks.
108+
* **Configuration File:** `/config/sync/views.view.block_content.yml`
109+
* **Archive:** Displays all content, grouped by month.
110+
* **Configuration File:** `/config/sync/views.view.archive.yml`
111+
112+
## User Roles
113+
114+
User roles define content access and management permissions for different user groups.
115+
116+
* **Administrator:** Has full system access.
117+
* **Configuration File:** `/config/sync/user.role.administrator.yml`
118+
* **Authenticated user:** Basic access for logged-in users.
119+
* **Permissions:** `access content`, `create code_contribution content`, `create event_contribution content`, `create issue content`, `create non_code_contribution content`.
120+
* **Configuration File:** `/config/sync/user.role.authenticated.yml`
121+
* **Anonymous user:** Limited access for non-logged-in users.
122+
* **Permissions:** `access content`, `use text format restricted_html`.
123+
* **Configuration File:** `/config/sync/user.role.anonymous.yml`
124+
* **Contribution Moderator:** Moderates contributions.
125+
* **Permissions:** `access administration pages`, `administer nodes`, `edit any code_contribution content`, `edit any event content`.
126+
* **Configuration File:** `/config/sync/user.role.contribution_moderator.yml`
127+
* **API basic read:** Has access to API basic read permissions.
128+
* **Permissions:** `delete own files`, `send performance traces to sentry`, `view user email addresses`
129+
* **Configuration File:** `/config/sync/user.role.api_basic_read.yml`
130+
131+
## Block Content Types
132+
133+
Block content types define reusable content blocks that can be placed in different regions of the site.
134+
135+
* **Basic:** A basic block containing a title and a body.
136+
* **Configuration File:** `/config/sync/block_content.type.basic.yml`
137+
138+
## Social Authentication
139+
140+
* Implemented using the Social Auth module and enables user authentication through social media platforms like Google.
141+
* **Configuration File:** `/config/sync/social_auth.settings.yml`
142+
143+
## Content Moderation
144+
145+
* Content moderation is implemented using the flag module named `contribution_approval`. This allows moderation of `code_contribution`, `event_contribution`, and `non_code_contribution` content types.
146+
* **Configuration File:** `/config/sync/flag.flag.contribution_approval.yml`
147+
* The "Contribution Moderator" role has specific permissions to create, update, and approve contribution content.
148+
* **Configuration File:** `/config/sync/user.role.contribution_moderator.yml`
149+
150+
This comprehensive content structure ensures organized content management, well-defined user roles, and effective display of information within the application. Understanding these components is crucial for developing and maintaining the project.
151+
```

0 commit comments

Comments
 (0)