Stanford School of Humanities And Sciences HSDP

This codebase runs the Humanities and Sciences Drupal (or Digital) Platform a.k.a. HSDP. This platform runs 130+ sites for departments, programs, centers, councils, initiatives, etc. The platform is hosted on Acquia.

Overview

Note the following properties of this project:

• Default development branch: the current major version branch, e.g. 12.x
• Production release branch: main
• Development branching convention: branch off the current major development branch
• Development environments: GitHub Codespaces, DDEV, Lando, or bare metal LAMP
• Local drush alias: @<SITE_ALIAS>.local
• Local site URL: http://<SITE_ALIAS>.suhumsci.loc

AI-Assisted Development

AI coding agents (Claude Code, OpenCode, Codex, Cursor, etc.) should read AGENTS.md before making changes. It contains AI-specific instructions and pointers to the documentation relevant for each task type (config work, patching, frontend work, tests, documentation, operational tasks), plus core rules and a pre-finish verify checklist. CLAUDE.md points there as well.

Repository Layout

Custom code lives in several locations; there is no web/ directory. How you change code depends on which location it lives in. Check this before editing.

What	Where	How to manage
Primary custom modules (hs_*)	docroot/modules/humsci/	Owned by this repo. Edit in place and commit directly here.
Secondary custom modules (stanford_*) used on many Stanford Drupal sites	docroot/modules/custom/	Composer-installed from upstream su-sws/* repositories. This directory is gitignored, so direct edits are overwritten on the next composer install. To change one of these modules, fork the upstream repo, open a PR there, and apply the change as a local patch in this repo via composer.json until it merges upstream and ships in a release. Then remove the patch. See Patching.
Installation profile	docroot/profiles/humsci/su_humsci_profile/	Owned by this repo. Edit in place. Has its own webpack build for JS and styles.
Profile submodules	docroot/profiles/humsci/su_humsci_profile/modules/	Owned by this repo. Edit in place and commit directly here.
Preact islands (select combobox)	docroot/profiles/humsci/su_humsci_profile/js/select-lists/	Owned by this repo. Self-contained yarn project; edit src/ and run yarn build. See Frontend Patterns.
Custom themes	docroot/themes/humsci/	Owned by this repo. Edit source in humsci_basic/src/ and rebuild. See Frontend Patterns.
Drupal core	docroot/core/	Composer-installed. Modified only via local patches. See Patching.
Contrib modules and themes	docroot/modules/contrib/, docroot/themes/contrib/	Added via Composer. Modified only via local patches. See Patching.
Frontend libraries (chosen, colorbox, dropzone, swiper, etc.)	docroot/libraries/	Composer-installed. Modified only via local patches. See Patching.
Site-specific settings	docroot/sites/<SITENAME>/	Owned by this repo. Provisioned by drush sws:multisite:new-site. See Provisioning a New Site.
Default site	docroot/sites/default/	Owned by this repo. Edit in place.
Shared settings includes (Acquia, global, local, SAML, fast 404, environment indicator)	docroot/sites/settings/	Owned by this repo. Edit in place; default.global.settings.php applies settings to every site.
Private files (per site)	files-private/	Runtime file storage, gitignored.
Global config	config/default/	Exported from a clean local environment. See Configuration Management.
Environment splits	config/envs/	Exported with the split enabled. See Configuration Management.
Drush commands	drush/Commands/	Owned by this repo. Edit in place.
Vendored Drush commands (SWSDC)	drush/Commands/contrib/sws-drush-commands/	Composer-installed from su-sws/sws-drush-commands; provides the sws: commands.
Drush site aliases (one per site)	drush/sites/	Generated by provisioning. See Provisioning a New Site.
Drush config (multisite list)	drush/drush.yml	Maintained by provisioning; one entry per site.
Patches	patches/core/, patches/contrib/	Stored locally and referenced from composer.json. See Patching.
Acquia Cloud hooks (common, dev, test, prod)	hooks/	Owned by this repo. Edit in place.
CI workflows (tests, PHPCS, PHPStan, dependency updates, release, deploy)	.github/workflows/	Owned by this repo. Edit in place.
Tugboat preview config	.tugboat/	Owned by this repo. Edit in place.
DDEV config	.ddev/	Owned by this repo. See the DDEV instructions.
GitHub Codespaces config	.devcontainer/	Owned by this repo. See GitHub Codespaces.
Lando config (legacy)	lando/	Legacy local environment. See the Lando instructions.
PHPUnit config	tests/phpunit/	Owned by this repo. Edit example.phpunit.xml, not the generated file. See Testing.
Codeception tests	tests/codeception/	Owned by this repo. See Testing.
Codeception test artifacts	artifacts/	Generated test output, gitignored.
Static analysis configs (PHPStan, PHPCS, Rector)	phpstan.neon, phpcs.xml, rector.php	Owned by this repo. See Coding Standards.
BackstopJS visual regression config	backstop.json	Owned by this repo. See the humsci_basic readme.
Drupal recipes	recipes/	Owned by this repo. Place custom and downloaded recipes here.

Module Ownership by Domain

Extend the module that owns a topic rather than creating a new one or duplicating logic. New custom modules go in docroot/modules/humsci/ with the hs_ prefix.

• Content types and entities: hs_basic_page, hs_person, hs_news, hs_events, hs_event_series, hs_research, hs_publications, hs_cmap, hs_courses
• Paragraphs and layout: hs_paragraph_types, hs_layouts, hs_blocks
• Config stack: hs_config_partial, hs_config_prefix, hs_config_readonly, hs_config_overrides
• Admin and Drush: hs_admin, hs_dashboard, hs_editorial, hs_masquerade, hs_role_description
• Integrations: hs_siteimprove, hs_capx, hs_migrate
• Field and views helpers: hs_field_helpers, hs_views_helper, hs_entities, hs_table_filter
• docroot/modules/custom/: stanford_fields, stanford_media, stanford_migrate, stanford_samlauth, ckeditor5_plugins
• Profile submodules: humsci_default_content, humsci_events_listeners

BLT to SWS Drush Commands (SWSDC) Migration

In April 2026 this repository moved from using BLT to SWS Drush Commands (SWSDC). If you are still using BLT and have not set up SWSDC, please read the migration documentation.

Documentation

Standards & Reference

• Algolia Search
• Branching Strategy
• CAP Profiles Importer
• Coding Standards (PHPStan, PHPCS, review patterns, etc.)
• Configuration Management
• Development Requirements
• Documentation Standards
• Frontend Patterns
• GitHub Codespaces
• Module Evaluation
• Tugboat Previews

Process Guides

• GitHub Codespaces Workflow
• Release and Code Deployment
• Site Launch
• Provisioning a New Site
• Copying a Site
• Decommissioning and Deleting a Site
• Upgrading Drupal Core
• Dependency Update Review
• Patching
• Deprecating and Removing a Module
• Testing

Migration

• BLT to SWSDC Migration

Note: Additional README files exist throughout the project in subdirectories for component-specific documentation. If you notice documentation that is incorrect or outdated, open a pull request with corrections.

Development Requirements

See Development Requirements.

Local Setup and Installation

You can run the site on GitHub Codespaces, DDEV, Lando, or bare metal.

Setup on GitHub Codespaces

GitHub Codespaces provides a cloud-based development environment with all dependencies pre-installed. This is the fastest way to get started.

• Follow the GitHub Codespaces Workflow guide to launch a codespace and push changes.
• Read the GitHub Codespaces guide for configuration and maintenance details.

Setup on DDEV or Lando

• Follow the DDEV instructions.
• Follow the Lando legacy instructions.

Setup on Bare Metal

1. Clone the repository and check out the current major development branch, for example 12.x.
2. Run composer install
3. Run drush sws:multisite:settings
4. Run drush sws:keys
5. Create or modify drush/local.drush.yml and add your local database settings and Acquia API key details. If used previously, your Acquia key can be found with cat ~/.acquia/cloud_api.conf. Otherwise log in to Acquia to create a new one.

   command:
     sws:
       options:
         db-port: '3306'
         db-host: localhost
         db-user: <DB_USER>
         db-pass: <DB_PASS>
         db-name: <DB_NAME>
         app-key: <ACQUIA_KEY>
         app-secret: <ACQUIA_SECRET>

   Warning: Never commit drush/local.drush.yml or any file containing credentials to the repository. Verify credential files are listed in .gitignore before committing.

6. For a clean installation run drush sws:multisite:install. Optionally add --site=<SITENAME> to install a specific multisite.
7. To sync from a live site: drush drupal:sync --site=<SITENAME>

Builds

Theme assets (Sass and JS) are compiled with webpack via npm scripts.

• npm run theme-build: Compile Sass for production for all themes based on humsci_basic.
• npm run theme-watch: Compile a CSS build and watch for changes in the existing .scss files in all themes based on humsci_basic.
• npm run theme-visreg: Run Percy VRT on hs_colorful and hs_traditional sites (see docroot/themes/humsci/humsci_basic/README.md for details.)

The build process automatically detects whether to run inside DDEV or Lando. To override:

• export HSDP_COMPILE_ENVIRONMENT=ddev
• export HSDP_COMPILE_ENVIRONMENT=lando
• export HSDP_COMPILE_ENVIRONMENT=baremetal

Testing

See Testing for how to run the PHPUnit and Codeception suites, and a list of current Codeception tests.

Sass

• npm test: Run tests for all Sass in the project (including humsci_basic).

Custom Drush Commands

• drush humsci:reports:users-by-role <ROLE> --env=prod: Generate a CSV or JSON report of users assigned to a role across all sites. Run with --help for all options.
• drush humsci:multisite:cron:run <JOB_ID> --force: Run one Ultimate Cron job on every site, for example hs_algolia_cron. Intended for Acquia scheduled jobs that need a single hook on its own interval.

Architecture Decision Records (ADRs)

Architecture Decision Records (ADRs) are used to document important architectural decisions made in this project. The ADR process and format are explained in 0000-record-architecture-decisions.md. All significant architectural decisions should be documented as a new ADR in the docs/architecture/decisions/ directory.

Glossary

Term	Definition
HSDP	Humanities and Sciences Drupal Platform: the name for this multi-site Drupal application
SWSDC	SWS Drush Commands: the custom Drush command library that replaced BLT. Commands are prefixed with drush sws:
<major>.x	The current major version development branch (e.g., 12.x). This is the default branch and base for all feature work
<major>.x-build	The deployment artifact branch generated from <major>.x and deployed to staging
Staging	The pre-production Acquia environment. Called "staging" in documentation and "test" in Acquia infrastructure, ACLI commands, and drush aliases (e.g., @<SITENAME>.test)
Drush alias	Site identifier used in drush commands. Derived from the site URL: dashes become underscores (_), dots become double underscores (__). Example: my-site.stanford.edu → alias my_site
ADR	Architecture Decision Record: a short document capturing a significant architectural decision, its context, and its consequences. Stored in docs/architecture/decisions/
Artifact tag	A deployable release tag in the format YYYY-MM-DD_VERSION (e.g., 2026-06-03_12.1.1) pushed to Acquia Cloud by release automation

Resources

• GitHub
• Acquia Cloud subscription