diff --git a/.circleci/config.yml b/.circleci/config.yml index 1473e5abfa..2115060f41 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -172,6 +172,12 @@ job-build: &job-build - run: name: Lint code with NPM linters command: docker compose exec -T cli bash -c "npm run --prefix \${DREVOPS_WEBROOT}/themes/contrib/\${DRUPAL_THEME} lint" || [ "${DREVOPS_CI_NPM_LINT_IGNORE_FAILURE:-0}" -eq 1 ] + - run: + name: Lint Drupal theme configuration + command: docker compose exec -T cli bash -c "./scripts/lint-theme-config.sh" || [ "${DREVOPS_CI_DRUPAL_THEME_CONFIG_LINT_IGNORE_FAILURE:-0}" -eq 1 ] + - run: + name: Lint Drupal theme schema + command: docker compose exec -T cli bash -c "./vendor/bin/drush inspect_config civictheme.settings --detail --only-error" - run: name: Run tooling tests command: ./scripts/test-tooling.sh @@ -240,6 +246,12 @@ job-build-no-persist: &job-build-no-persist - run: name: Lint code with NPM linters command: docker compose exec -T cli bash -c "npm run --prefix \${DREVOPS_WEBROOT}/themes/contrib/\${DRUPAL_THEME} lint" || [ "${DREVOPS_CI_NPM_LINT_IGNORE_FAILURE:-0}" -eq 1 ] + - run: + name: Lint Drupal theme configuration + command: docker compose exec -T cli bash -c "./scripts/lint-theme-config.sh" || [ "${DREVOPS_CI_DRUPAL_THEME_CONFIG_LINT_IGNORE_FAILURE:-0}" -eq 1 ] + - run: + name: Lint Drupal theme schema + command: docker compose exec -T cli bash -c "./vendor/bin/drush inspect_config civictheme.settings --detail --only-error" - run: name: Run tooling tests command: ./scripts/test-tooling.sh @@ -335,28 +347,28 @@ jobs: build-govcms: <<: *container_config environment: - DREVOPS_DRUPAL_PROFILE: govcms - DREVOPS_LINT_CONFIG_ALLOW_FAILURE: 1 + DRUPAL_PROFILE: govcms + DREVOPS_CI_DRUPAL_THEME_CONFIG_LINT_IGNORE_FAILURE: 1 <<: *job-build-no-persist # GovCMS profile, no subtheme. build-govcms-no-subtheme: <<: *container_config environment: - DREVOPS_DRUPAL_PROFILE: govcms + DRUPAL_PROFILE: govcms CIVICTHEME_SUBTHEME_ACTIVATION_SKIP: 1 CIVICTHEME_LIBRARY_INSTALL_SKIP: 1 - DREVOPS_LINT_CONFIG_ALLOW_FAILURE: 1 + DREVOPS_CI_DRUPAL_THEME_CONFIG_LINT_IGNORE_FAILURE: 1 <<: *job-build # GovCMS profile, subtheme is a sibling. build-govcms-sibling: <<: *container_config environment: - DREVOPS_DRUPAL_PROFILE: govcms + DRUPAL_PROFILE: govcms CIVICTHEME_INSTALL_SIBLING: 1 - DREVOPS_LINT_CONFIG_ALLOW_FAILURE: 1 - DREVOPS_TEST_BEHAT_TAGS: smoke + DREVOPS_CI_DRUPAL_THEME_CONFIG_LINT_IGNORE_FAILURE: 1 + DREVOPS_CI_BEHAT_PROFILE: smoke <<: *job-build-no-persist # Drupal 10, minimal profile, 'corporate' content profile. @@ -366,8 +378,8 @@ jobs: CIVICTHEME_CONTENT_PROFILE: corporate CIVICTHEME_SUBTHEME_ACTIVATION_SKIP: 1 CIVICTHEME_LIBRARY_INSTALL_SKIP: 1 - DREVOPS_LINT_CONFIG_ALLOW_FAILURE: 1 - DREVOPS_TEST_BEHAT_TAGS: smoke + DREVOPS_CI_DRUPAL_THEME_CONFIG_LINT_IGNORE_FAILURE: 1 + DREVOPS_CI_BEHAT_PROFILE: smoke <<: *job-build-no-persist # Drupal 10, minimal profile, 'highereducation' content profile. @@ -377,8 +389,8 @@ jobs: CIVICTHEME_CONTENT_PROFILE: highereducation CIVICTHEME_SUBTHEME_ACTIVATION_SKIP: 1 CIVICTHEME_LIBRARY_INSTALL_SKIP: 1 - DREVOPS_LINT_CONFIG_ALLOW_FAILURE: 1 - DREVOPS_TEST_BEHAT_TAGS: smoke + DREVOPS_CI_DRUPAL_THEME_CONFIG_LINT_IGNORE_FAILURE: 1 + DREVOPS_CI_BEHAT_PROFILE: smoke <<: *job-build-no-persist # Drupal 10, minimal profile, 'government' content profile. @@ -388,8 +400,8 @@ jobs: CIVICTHEME_CONTENT_PROFILE: government CIVICTHEME_SUBTHEME_ACTIVATION_SKIP: 1 CIVICTHEME_LIBRARY_INSTALL_SKIP: 1 - DREVOPS_LINT_CONFIG_ALLOW_FAILURE: 1 - DREVOPS_TEST_BEHAT_TAGS: smoke + DREVOPS_CI_DRUPAL_THEME_CONFIG_LINT_IGNORE_FAILURE: 1 + DREVOPS_CI_BEHAT_PROFILE: smoke <<: *job-build-no-persist # Isolated theme build. diff --git a/CI.md b/CI.md deleted file mode 100644 index fc48060f3a..0000000000 --- a/CI.md +++ /dev/null @@ -1,11 +0,0 @@ -# Automated builds (Continuous Integration) - -In software engineering, continuous integration (CI) is the practice of merging all developer working copies to a shared mainline several times a day. -Before feature changes can be merged into a shared mainline, a complete build must run and pass all tests on CI server. - -This project uses [Circle CI](https://circleci.com/) as a CI server: it imports production backups into fully built codebase and runs code linting and tests. When tests pass, a deployment process is triggered for nominated branches (usually, `master` and `develop`). - -Add `[skip ci]` to the commit subject to skip CI build. Useful for documentation changes. - -## SSH -Circle CI supports shell access to the build for 120 minutes after the build is finished when the build is started with SSH support. Use "Rerun job with SSH" button in Circle CI UI to start build with SSH support. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index abf5bcd42e..0000000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,128 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -support@drevops.com. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md deleted file mode 100644 index 99bd3a1303..0000000000 --- a/DEPLOYMENT.md +++ /dev/null @@ -1,34 +0,0 @@ -# Deployment process - -This project is deployed to the Salsa Digital hosting Lagoon instance. -Deployments are initiated by the Continuous Integration (CI) process on each -push to the `master`, `develop`, `release/*`, and `feature/*` branches, -provided all tests pass. - -## Pull Request (PR) Environments - -1. Developers create code on their local machine. -2. The code is then pushed to GitHub and a pull request is opened for the change. -3. The CI process monitors for code changes and initiates an automated build. -4. Once all tests pass at the end of the build, the CI process triggers a - deployment to Lagoon. -5. A PR environment with the name of the PR is established upon deployment. Any - pending update hooks and other deployment operations are executed during - deployment. - -When a PR is closed, its environment is automatically removed. - -## Content Profile Preview Environments - -Content profiles are employed to capture content for industry-specific demo -sites. Each content profile is automatically deployed to a preview environment -during development (hosted on this project's Lagoon instance) and to a -LaunchPad-based Lagoon instance upon release (handled outside of the -CivicTheme team). - -The development preview environments are redeployed by the CI on each successful -build in the `develop` branch. This ensures the deployability of content profile -sites with each code change. - -For a list of demo site URLs for development sites, refer to the main -[README.md](README.md#content-profiles). diff --git a/FAQs.md b/FAQs.md deleted file mode 100644 index 3b79dd6f9a..0000000000 --- a/FAQs.md +++ /dev/null @@ -1,90 +0,0 @@ -# FAQs - -## How to know which commands are available? -``` -ahoy help -``` - -## How to pass CLI arguments to commands? -``` -ahoy mycommand -- myarg1 myarg2 --myoption1 --myoption2=myvalue -``` - -## How to clear Drupal cache? -``` -ahoy drush -- cr -``` - -## How to login to Drupal site? -``` -ahoy login -``` - -## How to connect to the database? -1. Run `ahoy info` and grab the DB host port number. -2. Use these connection details: - - Host: `127.0.0.1` - - Username: `drupal` - - Password: `drupal` - - Database: `drupal` - - Port: the port from step 1 - -## How to run Livereload? -1. If `settings.local.php` does not exist, copy `default.settings.local.php` to `settings.local.php` -2. Set `$settings['livereload'] = TRUE;` in `settings.local.php` file -3. Clear drupal cache `ahoy drush cr` -4. Run: `ahoy few` - -## How to use Xdebug? -1. Run `ahoy debug` -2. Enable listening for incoming debug connections in your IDE. -3. If required, provide server URL to your IDE as it appears in the browser. -4. Enable Xdebug flag in the request coming from your web browser (use one of - the extensions or add `?XDEBUG_SESSION_START=1` to your URL). -5. Set a breakpoint in your IDE and perform a request in the web browser. - -Use the same commands to debug CLI scripts. - -Use `ahoy up` to restart the stack without Xdebug enabled. - -## How to use Xdebug on Behat scripts? -1. Enable debugging: `ahoy debug` -2. Enter CLI container: `ahoy cli` -3. Run Behat tests: - ``` - vendor/bin/behat path/to/test.feature - ``` - -## What should I do to switch to a "clean" branch environment? -Provided that your stack is already running: -1. Switch to your branch -2. `composer install` -3. `ahoy site-install` - -Note that you do not need to rebuild the full stack using `ahoy build` every time. -However, sometimes you would want to have an absolutely clean environment - in that -case, use `ahoy build`. - -## How to just import the database? -Provided that your stack is already running: -`ahoy drush sql-drop -y; ahoy drush sql-cli < .data/db.sql` - -## How to add Drupal modules - -`composer require drupal/module_name` - -## Adding patches for Drupal modules - -1. Add `title` and `url` to patch on https://drupal.org to the `patches` array in `extra` section in `composer.json`. - -``` - "extra": { - "patches": { - "drupal/core": { - "Contextual links should not be added inside another link - https://www.drupal.org/node/2898875": "https://www.drupal.org/files/issues/contextual_links_should-2898875-3.patch" - } - } - } -``` - -2. `composer update --lock` diff --git a/README.md b/README.md index 59c5cd896a..d52a577c7c 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ Copy `docker-compose.override.default.yml` to `docker-compose.override.yml`. ## Project documentation +- [Development](docs/development.md) - [FAQs](docs/faqs.md) - [Testing](docs/testing.md) - [CI](docs/ci.md) diff --git a/RELEASING.md b/RELEASING.md deleted file mode 100644 index 1214171021..0000000000 --- a/RELEASING.md +++ /dev/null @@ -1,39 +0,0 @@ -# Releasing - -[git-flow](https://danielkummer.github.io/git-flow-cheatsheet/) is used to manage releases. - -## Release outcome - -1. Release branch exists as `release/X.Y.Z` in GitHub repository. -2. Release tag exists as `X.Y.Z` in GitHub repository. -3. The `HEAD` of the `master` branch has `X.Y.Z` tag. -4. The hash of the `HEAD` of the `master` branch exists in the `develop` branch. This is to ensure that everything pushed to `master` exists in `develop` (in case if `master` had any hot-fixes that not yet have been merged to `develop`). -5. There are no PRs in GitHub related to the release. - -## Version Number - -Release versions are numbered according to [Semantic Versioning](https://semver.org/). -Given a version number X.Y.Z: -* X = Major release version. No leading zeroes. -* Y = Minor Release version. No leading zeroes. -* Z = Hotfix/patch version. No leading zeroes. - -Examples: -* Correct: `0.1.0`, `1.0.0` , `1.0.1` , `1.0.10` -* Incorrect: `0.1` , `1` , `1.0` , `1.0.01` , `1.0.010` - -## Multi-repository releases - -This repository is a mono-repository, meaning that it contains multiple packages -that are published to other repositories on every commit to `develop` branch. - -Releasing to this repository will not create releases in other repositories. -This was done purposefully to avoid creating releases in other repositories -when there are no changes in them and to allow having own versions in published -repositories as changes in this repository do not necessarily mean that there -are changes in published repositories. - -Release log of this repository must contain all the changes that were made to -all the packages that are published from this repository. -Parts of the release log can then be manually copied to the release logs of -published repositories. diff --git a/TESTING.md b/TESTING.md deleted file mode 100644 index b5d3970a2e..0000000000 --- a/TESTING.md +++ /dev/null @@ -1,68 +0,0 @@ -# Testing - -## Authoring tests - -This repository uses different types of tests: -1. Unit, Functional and Kernel tests for Drupal modules and themes. -2. Bats tests to test tooling and scripts. -3. Behat tests to test overall end-to-end Drupal site functionality. - -### Behat tests -Behat configuration uses multiple extensions: -- [Drupal Behat Extension](https://github.com/jhedstrom/drupalextension) - Drupal integration layer. Allows to work with Drupal API from within step definitions. -- [Behat Screenshot Extension](https://github.com/integratedexperts/behat-screenshot) - Behat extension and a step definition to create HTML and image screenshots on demand or test fail. -- [Behat Progress Fail Output Extension](https://github.com/integratedexperts/behat-format-progress-fail) - Behat output formatter to show progress as TAP and fail messages inline. Useful to get feedback about failed tests while continuing test run. -- `FeatureContext` - Site-specific context with custom step definitions. - -Add `@skipped` tag to failing tests if you would like to skip them. - -### Authoring schema update tests - -> Available from CivicTheme 1.5 - -CivicTheme provides configuration for content types, fields and site settings. -These can change with versions of the theme. To ensure that the changes are -applied correctly in the consumer site's database, we use -[schema update tests](web/themes/contrib/civictheme/tests/src/Functional/Update). - -These types of tests require a database of the site with the previous -version of the module or theme installed to be available to the test. - -In CivicTheme, we use "bare" and "filled" database dumps to test schema updates: -- "bare" database dump contains only the schema and no content. -- "filled" database dump contains the schema and the content. - -For simplicity, we only test on the `minimal` profile and the latest Drupal version. - -To update the database dumps: - -1. Checkout this repository at the specific CivicTheme release (1.3 or newer). - Note that some of the environment variables are only available in the latest - version of the repository and you may need to adjust them below to the version - you are using (e.g. `SKIP_LIBRARY_INSTALL` was in version `1.3.2` and now is - called `CIVICTHEME_LIBRARY_INSTALL_SKIP` in `1.5.0`). -2. Update "bare" database dump: - ```bash - export CIVICTHEME_VERSION= # update to your version - export DREVOPS_DRUPAL_VERSION=10 - export DREVOPS_DRUPAL_VERSION_FULL=10.0.0-rc1 - export DREVOPS_DRUPAL_PROFILE=minimal - DREVOPS_DRUPAL_INSTALL_OPERATIONS_SKIP=1 ahoy build - ahoy cli "DREVOPS_DRUPAL_PROFILE=minimal scripts/custom/drupal-install-site-1-enable-modules.sh" - mkdir -p web/themes/contrib/civictheme/tests/fixtures/updates - ahoy cli php web/core/scripts/dump-database-d8-mysql.php | gzip > "web/themes/contrib/civictheme/tests/fixtures/updates/drupal_${DREVOPS_DRUPAL_VERSION_FULL}.${DREVOPS_DRUPAL_PROFILE}.civictheme_${CIVICTHEME_VERSION}.bare.php.gz" - ``` -3. Update "filled" database dump: - ```bash - export CIVICTHEME_VERSION= # update to your version - export DREVOPS_DRUPAL_VERSION=10 - export DREVOPS_DRUPAL_VERSION_FULL=10.0.0-rc1 - export DREVOPS_DRUPAL_PROFILE=minimal - DREVOPS_DRUPAL_INSTALL_OPERATIONS_SKIP=1 ahoy build - ahoy cli "DREVOPS_DRUPAL_PROFILE=minimal scripts/custom/drupal-install-site-1-enable-modules.sh" - ahoy cli "drush php:eval -v \"require_once '/app/web/themes/contrib/civictheme/theme-settings.provision.inc'; civictheme_provision_cli();\"" - ahoy cli "GENERATED_CONTENT_CREATE=1 drush pm:enable cs_generated_content -y" - ahoy cli "GENERATED_CONTENT_DELETE_SKIP=1 drush pm:uninstall cs_generated_content generated_content -y" - mkdir -p web/themes/contrib/civictheme/tests/fixtures/updates - ahoy cli php web/core/scripts/dump-database-d8-mysql.php | gzip > "web/themes/contrib/civictheme/tests/fixtures/updates/drupal_${DREVOPS_DRUPAL_VERSION_FULL}.${DREVOPS_DRUPAL_PROFILE}.civictheme_${CIVICTHEME_VERSION}.filled.php.gz" - ``` diff --git a/behat.yml b/behat.yml index 90e07b49b7..b140a969db 100644 --- a/behat.yml +++ b/behat.yml @@ -67,3 +67,10 @@ p1: cache: '/tmp/behat_gherkin_cache' filters: tags: "@smoke,@p1&&~@skipped&&~@subtheme" + +# Profile for smoke ttesting. +smoke: + gherkin: + cache: '/tmp/behat_gherkin_cache' + filters: + tags: "@smoke&&~@skipped&&~@subtheme" diff --git a/docs/deployment.md b/docs/deployment.md index a30c403736..99bd3a1303 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,30 +1,34 @@ # Deployment process -Refer to https://docs.drevops.com/latest/usage/deploy for more information. +This project is deployed to the Salsa Digital hosting Lagoon instance. +Deployments are initiated by the Continuous Integration (CI) process on each +push to the `master`, `develop`, `release/*`, and `feature/*` branches, +provided all tests pass. -## Workflow +## Pull Request (PR) Environments -1. Code is authored on a local machine by a developer. -2. Once the code is ready, it is pushed to GitHub. A pull request needs to be - opened for this code change. -3. The CI "listens" for code changes and will start an automated build. -4. At the end of the build, when all tests have passed, the CI will trigger a +1. Developers create code on their local machine. +2. The code is then pushed to GitHub and a pull request is opened for the change. +3. The CI process monitors for code changes and initiates an automated build. +4. Once all tests pass at the end of the build, the CI process triggers a deployment to Lagoon. -5. Once deployed, a PR environment will appear with a PR name. The database will - be taken from production environment. - All pending update hooks and other deployment operations will run during +5. A PR environment with the name of the PR is established upon deployment. Any + pending update hooks and other deployment operations are executed during deployment. -Once PR is closed, the environment will be automatically removed. +When a PR is closed, its environment is automatically removed. +## Content Profile Preview Environments +Content profiles are employed to capture content for industry-specific demo +sites. Each content profile is automatically deployed to a preview environment +during development (hosted on this project's Lagoon instance) and to a +LaunchPad-based Lagoon instance upon release (handled outside of the +CivicTheme team). -## Database refresh in Lagoon environments - -To fresh the database in the existing Lagoon environment with the database from -production environment, run: - -``` -DREVOPS_DEPLOY_BRANCH= DREVOPS_DEPLOY_PROCEED=1 DREVOPS_DEPLOY_ACTION=deploy_override_db ahoy deploy -``` +The development preview environments are redeployed by the CI on each successful +build in the `develop` branch. This ensures the deployability of content profile +sites with each code change. +For a list of demo site URLs for development sites, refer to the main +[README.md](README.md#content-profiles). diff --git a/DEVELOPMENT.md b/docs/development.md similarity index 87% rename from DEVELOPMENT.md rename to docs/development.md index 4f58d92446..395ee60ba5 100644 --- a/DEVELOPMENT.md +++ b/docs/development.md @@ -42,8 +42,7 @@ By default, the site: Override the default behavior using these environment variables: -- `DREVOPS_DRUPAL_VERSION=10` - Installs the Drupal 10 version. -- `DREVOPS_DRUPAL_PROFILE=minimal` - Uses the `minimal` profile for installation. +- `DRUPAL_PROFILE=minimal` - Uses the `minimal` profile for installation. For Drupal 10, this becomes the enforced default. - `CIVICTHEME_SUBTHEME_ACTIVATION_SKIP=1` - Omits activation of the demo sub-theme. @@ -59,13 +58,9 @@ without full rebuild). Example: ```bash -# Install Drupal 10 site using `minimal` profile with CivicTheme Demo -# sub-theme and provision demo content. -DREVOPS_DRUPAL_VERSION=10 ahoy install-site - -# Install Drupal 10 site using `minimal` profile with CivicTheme. +# Install Drupal site using `minimal` profile with CivicTheme. # Do not create a sub-theme and do not provision demo content. -DREVOPS_DRUPAL_VERSION=10 CIVICTHEME_SUBTHEME_ACTIVATION_SKIP=1 CIVICTHEME_LIBRARY_INSTALL_SKIP=1 CIVICTHEME_GENERATED_CONTENT_CREATE_SKIP=1 ahoy install-site +CIVICTHEME_SUBTHEME_ACTIVATION_SKIP=1 CIVICTHEME_LIBRARY_INSTALL_SKIP=1 CIVICTHEME_GENERATED_CONTENT_CREATE_SKIP=1 ahoy install-site ``` ## Compiling theme assets @@ -143,7 +138,7 @@ These steps are captured below: ```bash # Step 1: Install a site with the desired content profile. export CIVICTHEME_CONTENT_PROFILE=default -DREVOPS_DRUPAL_PROFILE=minimal CIVICTHEME_SUBTHEME_ACTIVATION_SKIP=1 CIVICTHEME_GENERATED_CONTENT_CREATE_SKIP=1 ahoy install-site +DRUPAL_PROFILE=minimal CIVICTHEME_SUBTHEME_ACTIVATION_SKIP=1 CIVICTHEME_GENERATED_CONTENT_CREATE_SKIP=1 ahoy install-site # Step 2: Make changes. # ... diff --git a/docs/releasing.md b/docs/releasing.md index 33597faf6a..614e1791ae 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -35,3 +35,20 @@ Examples: * Correct: `0.1.0`, `1.0.0` , `1.0.1` , `1.0.10` * Incorrect: `0.1` , `1` , `1.0` , `1.0.01` , `1.0.010` + +## Multi-repository releases + +This repository is a mono-repository, meaning that it contains multiple packages +that are published to other repositories on every commit to `develop` branch. + +Releasing to this repository will not create releases in other repositories. +This was done purposefully to avoid creating releases in other repositories +when there are no changes in them and to allow having own versions in published +repositories as changes in this repository do not necessarily mean that there +are changes in published repositories. + +Release log of this repository must contain all the changes that were made to +all the packages that are published from this repository. +Parts of the release log can then be manually copied to the release logs of +published repositories. + diff --git a/docs/testing.md b/docs/testing.md index c217b6b8a0..8e093f7845 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,3 +1,69 @@ # Testing -Refer to https://docs.drevops.com/latest/workflow/test/ for more information. +## Authoring tests + +This repository uses different types of tests: +1. Unit, Functional and Kernel tests for Drupal modules and themes. +2. Bats tests to test tooling and scripts. +3. Behat tests to test overall end-to-end Drupal site functionality. + +### Behat tests + +Behat configuration uses multiple extensions: +- [Drupal Behat Extension](https://github.com/jhedstrom/drupalextension) - Drupal integration layer. Allows to work with Drupal API from within step definitions. +- [Behat Screenshot Extension](https://github.com/integratedexperts/behat-screenshot) - Behat extension and a step definition to create HTML and image screenshots on demand or test fail. +- [Behat Progress Fail Output Extension](https://github.com/integratedexperts/behat-format-progress-fail) - Behat output formatter to show progress as TAP and fail messages inline. Useful to get feedback about failed tests while continuing test run. +- `FeatureContext` - Site-specific context with custom step definitions. + +Add `@skipped` tag to failing tests if you would like to skip them. + +### Authoring schema update tests + +> Available from CivicTheme 1.5 + +CivicTheme provides configuration for content types, fields and site settings. +These can change with versions of the theme. To ensure that the changes are +applied correctly in the consumer site's database, we use +[schema update tests](web/themes/contrib/civictheme/tests/src/Functional/Update). + +These types of tests require a database of the site with the previous +version of the module or theme installed to be available to the test. + +In CivicTheme, we use "bare" and "filled" database dumps to test schema updates: +- "bare" database dump contains only the schema and no content. +- "filled" database dump contains the schema and the content. + +For simplicity, we only test on the `minimal` profile and the latest Drupal version. + +To update the database dumps: + +1. Checkout this repository at the specific CivicTheme release (1.3 or newer). + Note that some of the environment variables are only available in the latest + version of the repository and you may need to adjust them below to the version + you are using (e.g. `SKIP_LIBRARY_INSTALL` was in version `1.3.2` and now is + called `CIVICTHEME_LIBRARY_INSTALL_SKIP` in `1.5.0`). +2. Update "bare" database dump: + ```bash + export CIVICTHEME_VERSION= # update to your version + export DRUPAL_VERSION=10 + export DRUPAL_VERSION_FULL=10.0.0-rc1 + export DRUPAL_PROFILE=minimal + DREVOPS_PROVISION_POST_OPERATIONS_SKIP=1 ahoy build + ahoy cli "DRUPAL_PROFILE=minimal scripts/custom/drupal-install-site-1-enable-modules.sh" + mkdir -p web/themes/contrib/civictheme/tests/fixtures/updates + ahoy cli php web/core/scripts/dump-database-d8-mysql.php | gzip > "web/themes/contrib/civictheme/tests/fixtures/updates/drupal_${DRUPAL_VERSION_FULL}.${DRUPAL_PROFILE}.civictheme_${CIVICTHEME_VERSION}.bare.php.gz" + ``` +3. Update "filled" database dump: + ```bash + export CIVICTHEME_VERSION= # update to your version + export DRUPAL_VERSION=10 + export DRUPAL_VERSION_FULL=10.0.0-rc1 + export DRUPAL_PROFILE=minimal + DREVOPS_PROVISION_POST_OPERATIONS_SKIP=1 ahoy build + ahoy cli "DRUPAL_PROFILE=minimal scripts/custom/drupal-install-site-1-enable-modules.sh" + ahoy cli "drush php:eval -v \"require_once '/app/web/themes/contrib/civictheme/theme-settings.provision.inc'; civictheme_provision_cli();\"" + ahoy cli "GENERATED_CONTENT_CREATE=1 drush pm:enable cs_generated_content -y" + ahoy cli "GENERATED_CONTENT_DELETE_SKIP=1 drush pm:uninstall cs_generated_content generated_content -y" + mkdir -p web/themes/contrib/civictheme/tests/fixtures/updates + ahoy cli php web/core/scripts/dump-database-d8-mysql.php | gzip > "web/themes/contrib/civictheme/tests/fixtures/updates/drupal_${DRUPAL_VERSION_FULL}.${DRUPAL_PROFILE}.civictheme_${CIVICTHEME_VERSION}.filled.php.gz" + ```