Updated documentation. [skip ci]

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 ## Checklist before requesting a review
 
-- [ ] I have formatted the subject to include ticket number as `[CS-123] Verb in past tense with dot at the end.`
+- [ ] I have formatted the subject to include ticket number as `Issue #123456 by drupal_org_username: Issue title`
 - [ ] I have added a link to the issue tracker
 - [ ] I have provided information in `Changed` section about WHY something was done if this was not a normal implementation
 - [ ] I have performed a self-review of my code

docs/README.md

@@ -1,7 +1,8 @@
 # Project-specific documentation.
 
-- [Onboarding checklist](onboarding.md)
+- [Development.md](development.md)
 - [Testing](testing.md)
 - [CI](ci.md)
+- [Deployment.md](deployment.md)
 - [Releasing](releasing.md)
 - [FAQs](faqs.md)

docs/ci.md

@@ -8,7 +8,7 @@ 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`).
+(usually, `main` and `develop`).
 
 Refer to https://docs.drevops.com/latest/usage/ci for more information.
 
@@ -22,3 +22,17 @@ changes.
 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.
+
+## Build types
+
+In order to maintain the software quality we need to make sure that the code can run:
+1. On the current and next version of bare Drupal core
+2. On the current version of GovCMS
+3. As a standalone theme, sub-theme as a sibling and sub-theme as a custom theme
+4. On current and next version of PHP
+5. For content profiles
+6. For the modules we publish
+
+Having a full matrix of all variants is not feasible, so we run 2 types of builds:
+1. **Isolated** - installs the theme code on a fresh bare Drupal site using the build scripts from https://github.com/AlexSkrypnyk/drupal_extension_scaffold
+2. **Full build** - runs as if the theme code was installed on a `minimnal` or `govcms` profile with all custom modules enabled using the build scripts from https://github.com/drevops/scaffold

docs/deployment.md

@@ -2,7 +2,7 @@
 
 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,
+push to the `main`, `develop`, `release/*`, and `feature/*` branches,
 provided all tests pass.
 
 ## Pull Request (PR) Environments

docs/development.md

@@ -10,22 +10,43 @@ Before starting, ensure you have reviewed the documentation for
 [UI kit](https://docs.civictheme.io/ui-kit) and
 [Drupal theme](https://docs.civictheme.io/drupal-theme).
 
-## Local environment setup
 
-- Make sure that you have latest versions of all required software installed:
-  - [Docker](https://www.docker.com/)
-  - [Pygmy](https://github.com/pygmystack/pygmy)
-  - [Ahoy](https://github.com/ahoy-cli/ahoy)
-- Make sure that all local web development services are shut down (Apache/Nginx, Mysql, MAMP etc).
-- Checkout project repository (in one of the [supported Docker directories](https://docs.docker.com/docker-for-mac/osxfs/#access-control)).
-- `pygmy up`
-- `ahoy build`
+## Build types
 
-### Apple M1 adjustments
+There are 2 types of the build that can be run locally (same runs in CI):
 
-Copy `docker-compose.override.default.yml` to `docker-compose.override.yml`.
+1. **Isolated** - installs the theme code on a fresh bare Drupal site using the build scripts from https://github.com/AlexSkrypnyk/drupal_extension_scaffold
+2. **Full build** - runs as if the theme code was installed on a `minimnal` or `govcms` profile with all custom modules enabled using the build scripts from https://github.com/drevops/scaffold
 
-## Build process
+## Isolated
+
+The isolated build is used to test the theme code on a fresh Drupal site without
+any additional modules or themes. This build is useful to ensure that the theme
+code is compatible with the latest Drupal version and does not have any
+dependencies on other modules or themes.
+
+To run the isolated build, use the following command:
+
+```bash
+cd web/themes/contrib/civictheme
+ahoy build
+```
+
+This will assemble the full Drupal codebase in `web/themes/contrib/civictheme/build`
+directory and will symlink the CivicTheme theme files into the
+`web/themes/contrib/civictheme/build/web/themes/custom/civictheme` directory.
+
+**This does not use Docker and does not require a running Docker stack.**
+
+Important: make sure to removed `web/themes/contrib/civictheme/build` directory
+before running the `Full build` build to avoid any conflicts.
+
+## Full build (Docker build)
+
+The full build is used to test the theme code on a full Drupal site with all
+custom modules and themes enabled. This build is useful to ensure that the theme
+code is compatible with the latest Drupal version and the latest GovCMS version
+as well as with all custom modules.
 
 The following steps outline the build process:
 
@@ -76,7 +97,7 @@ Example:
 CIVICTHEME_SUBTHEME_ACTIVATION_SKIP=1 CIVICTHEME_GENERATED_CONTENT_CREATE_SKIP=1 ahoy provision
 ```
 
-## Compiling theme assets
+### Compiling theme assets
 
 To compile all assets in all themes: `ahoy fe`
 
@@ -95,13 +116,17 @@ cd web/themes/custom/civictheme_demo
 npm run build
 ```
 
-## Working with configurations
+Refer to the [theme's Readme](web/themes/contrib/civictheme/README.md) for more
+information about switching of the UIKit version and other theme-specific
+details.
+
+### Working with configurations
 
 Configuration is captured using [Config Devel](https://www.drupal.org/project/config_devel) module for:
 - CivicTheme theme into `config/install` and `config/optional` directories.
 - Development `civictheme_dev` module's `config/install` and `config/optional` directories.
 
-### Exporting configurations
+#### Exporting configurations
 
 ```bash
 ahoy export-config
@@ -121,7 +146,7 @@ Exclude certain configuration from automatically be added to `civictheme.info.ym
 by adding records to [theme_excluded_configs.txt](./scripts/theme_excluded_configs.txt).
 Note that wildcards are supported.
 
-### Validating configurations
+#### Validating configurations
 
 Configuration validation allows to ensure that all configuration is captured
 correctly and that there is no conflicting or duplicating configuration was
@@ -131,15 +156,15 @@ added to the codebase.
 ahoy lint-config
 ```
 
-## Working with content profiles
+### Working with content profiles
 
 Content profiles are used to capture content for the industry-specific demo
 sites. Each content profile is a separate submodule of `civictheme_content`
 module that contains content and configuration required to build a demo site.
 
 See main [README.md](README.md#content-profiles) for a list of demo site URLs.
 
-### Updating content
+#### Updating content
 
 The workflow to update the content within a content profile consists of 3 steps:
 

docs/faqs.md

@@ -114,11 +114,3 @@ composer require drupal/module_name
 ```bash
 composer update --lock`
 ```
-
-## 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`

docs/releasing.md

@@ -7,10 +7,10 @@ manage releases.
 
 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
+3. The `HEAD` of the `main` branch has `X.Y.Z` tag.
+4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch.
+   This is to ensure that everything pushed to `main` exists in `develop` (in
+   case if `main` had any hot-fixes that not yet have been merged
    to `develop`).
 5. There are no PRs in GitHub related to the release.
 
@@ -45,3 +45,16 @@ 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.
 
+## Releasing to Drupal.org
+
+Releases to Drupal.org are done manually.
+
+Every commit merged to the `develop` is pushed to Drupal.org to the `1.x-dev`
+branch, meaning that every commit may be used in a new release. This was done
+on purpose to avoid accidental releases done in GitHub (it is not possible to
+delete releases in Drupal.org).
+
+**The tags from this repository are not pushed to Drupal.org.**
+
+When a release is published as a tag in GitHub, the release version must be
+manually created in Drupal.org.