Skip to content

Latest commit

 

History

History
115 lines (82 loc) · 9.88 KB

development.md

File metadata and controls

115 lines (82 loc) · 9.88 KB

Getting started as a developer

PR Workflow

When you're working on a new ticket, you'll want to start with the latest develop branch, and rebuild that before you do your new work. Assuming you're followed the setup steps (specifically having run the npm run setup script) here's the recommended workflow for regular development:

  • git checkout develop
  • git pull
  • git checkout -b YALB-XXX-ticket-description
  • npm run build

After running those commands, you should have a clean environment to make your changes.

Updating Drupal configuration

Drupal's configuration management system organizes information about the structure and settings of the application into a consistent collection of structured data. Active configurations are typically stored in the site's database while staged configurations are stored in a series of YAML files. DevOps and version control tools will track changes to the YAML files to deploy configuration changes across different websites and environments. Changes made in a local development environment can be tested and released to the production website predictably.

Configuration in Drupal refers to many parts of the website including content types, vocabularies, field definitions, roles, permissions, WYSIWYG settings, media types, and views, among many other things. Instances of content (nodes, terms, users) and state variables are not considered configuration and will not be stored in version control.

Platform settings

All platform config files are stored in the yalesites_profile installation profile. YAML files are stored in the config/sync directory. This is a new approach to maintaining configuration without the need to edit file contents like the UUID. The project's settings.php ensures all sites use the profile configuration as the canonical source of site settings.

Process for updating

All configuration changes must be tracked in the profile repository. This includes changes to content types, fields, and module settings, among others. After making changes:

# Export configuration to update local YAML files.
lando drush cex -y
# Review changes.
git status
# If all looks well, then add and commit the set of configs.
git add config/sync

Best practices:

  1. Avoid making changes in production. Configuration should get created in a local development environment, exported, committed into the installation profile, and move through the development workflow.
  2. Avoid making manual changes to YAML files. The configuration files include many interdependencies and should be generated by Drupal as a complete set. All files should move through version control together.
  3. Export configuration regularly. Updating modules, adding custom code, and even interacting with seemingly unrelated admin forms can create changes in the active configuration. Check-in these changes regularly to ensure all sites stay in sync.

Creating a custom module

Custom functionality is added to the platform through Yale maintained modules. If the code is dependent on the architecture defined in the installation profile, then a custom module should be added directly to the yalesites_profile project. If the work is not inherently tied to YaleSites or if the code has value to other sites that are not on the platform, then the module can be created in a separate repository and added as contributed code.

# Navigate to the custom modules directory
cd web/profiles/contrib/yalesites_profile/modules/custom
# Custom modules are added directly to the profile repo.

Installing a contrib module or theme

Contributed projects extend the functionality of Drupal to add new features or alter existing functionality. Projects are added to the installation profile and pushed out to all sites on the platform. When developing locally, adding a project to the profile will not automatically rebuild the composer installed dependencies in the parent project. The following process may be followed when installing a contributed project in a local development environment.

# Navigate to the installation profile repository.
cd web/profiles/custom/yalesites_profile
# Require the new module without downloading packages in this folder.
lando composer require drupal/PROJECT --no-update
# Return the project repo root.
cd ../../../..
# Add the module to the project repository.
lando composer update @yalesites-org/yalesites_profile
# Do not check in changes to the top level composer.json file.
# Never check in the project's composer.lock file.

Updating a YaleSites theme

Contributed themes are added to the YaleSites platform as dependencies of the installation profile. Developers can make changes to the theme files directly.

# Navigate to the theme folder and update files ad needed.
cd web/themes/contrib/atomic
# Theme changes are committed in the theme's repository.

Frontend tasks may often require changes to the site's fields, content types, or displays. If this is the case, then developers can follow the above process for updating site configuration. These config settings are tracked in the yalesites_profile. An automated process has not yet been defined for deploying config changes and theme changes into the same multidev environment.

Working with Starterkit content

The ys_starterkit module defines content used to showcase how paragraphs and Drupal entities can be used together for site building. The content is also a useful tool for developers who want example pages for testing their work.

# Import content for the first time or update content.
lando drush migrate-import --group ys_starterkit
# Delete entities created from the migration.
lando drush migrate-rollback --group ys_starterkit
# Update partial configuration if altering the migration configuration.
lando drush cim --partial --source=/app/web/profiles/custom/yalesites_profile/modules/custom/ys_starterkit/config/install -y

Data model best practices

A well-structured data model ensures efficiency, maintainability, and scalability within the YaleSites platform. Below are some guiding principles adopted by the platform maintainers:

  • Documentation Maintenance: Keep the data model documentation up to date. This Teams document includes entity definitions, text formats, display mode definitions, and other content settings. Whenever there's a change to a content type, block, paragraph, taxonomy, or any other entity, make it a priority to update this central documentation source. Maintaining accurate documentation is crucial for team collaboration and project continuity.
  • Normalize Data: Follow established principles of database normalization to minimize data redundancy and enhance data integrity. Leverage reference fields and relationships to establish connections between related content instead of duplicating data. This approach ensures that the data remains consistent and predictable.
  • Reuse Fields: Reduce the proliferation of field definitions by reusing fields across multiple content bundles, as long as they serve a similar business purpose. For instance, if several content types (e.g., pull quote, video description, banner intro) require a 'field_text' storage, consider reusing this field definition to maintain consistency and simplify content management.
  • Avoid Single-Purpose Fields or Entities: When adding fields or entities, strive to make them versatile enough to fulfill multiple purposes across YaleSites. For example, while a dedicated 'Speaker' field might seem useful for an event content type, evaluate whether this feature could be addressed using a content-spotlight block. Add new fields only when they contribute to sorting, filtering, or theming content in specific ways.
  • Build with Blocks: Embrace the power of the layout builder by utilizing blocks to define new components. YaleSites relies on blocks for editorial controls and mapping content to the component library. This includes both custom blocks (content entities) and programmatically defined blocks (plugins).
  • Use Paragraphs for Nested Content: Paragraphs remain a valuable tool, particularly when dealing with components that contain an indeterminate number of children, such as accordion items, tab items, or gallery items. The Paragraphs module provides intuitive widgets that offer an effective editorial interface for managing reference content within these complex components.

Adding a 'dial' for theming a component

This project features custom fields for block theming. For example, the divider block includes settings for position, width, and animation style. In contrast to traditional Drupal projects using predefined list-field options in the configuration file, we've chosen a distinct approach. Our approach prioritizes the ability to add, remove, and dynamically adjust these options in future YaleSites themes and platform iterations, ensuring enduring flexibility. This system accommodates unique values for each field instance and supports changes over time, avoiding database integrity concerns. To add a dial:

  1. Begin by adding the desired style field to the custom block using the standard field UI. Whenever feasible, utilize an existing field like field_style_position, field_style_width, or field_style_variation.
  2. Configure the display of this field using the Field UI. Ensure that the style field is presented without a label and employs the 'key' formatter.
  3. Export the site configuration to generate all the associated field YAML files.
  4. In the event that this is a newly created field, update the field storage configuration file. Specify the callback function for values using allowed_values_function: ys_themes_allowed_values_function.
  5. Proceed to update the key-value pairs within ys_themes.component_overrides.yml. Remember to make these updates in two locations: the config/sync directory and the module/install directory.
  6. With these adjustments in place, you can now connect these values to components within the theme templates, achieving the desired styling and functionality.