Platform configuration

This guide is a living governance document for web leads who are contributing to the configuration of the SDSS multisite. What you build will be platform-wide and not site-specific. Working as a team to generalize what you build together will be beneficial to all, and will help keep front-end and maintenance costs low.

This guide currently applies to:

  • Vocabularies
  • Fields
  • Views
  • Content types

It does not include:

  • Styling
  • Display (with the exception of Views)

These items will require design, front-end development, and accessibility review.

What we are building

In general, you will be building things that you need for your website. Please refer to the the following criteria to consider. Can what you are building be made:

  • Reusable
  • Content-agnostic
  • Accessible

Caveats

  • Since individual tests won't be written for each feature, this process relies heavily on QA.

Process

The process of getting your site configuration from concept to production.

  1. Try your site-building on the SDSS Sandbox site. Get feedback on this version from other site owners.
  2. When you are ready to do the final build, we will do this one ticket at a time
    1. Communicate to the SDSS web leads what you are planning to build so we can avoid duplicate effort and naming conflicts
    2. Replicate the polished version of your work on the SDSS Configuration site. A Pull Request (PR) will be created that captures the configuration changes from your site-building. Please note that these changes will include configuration only... not content.
  3. The PR will be reviewed. If there are issues or conflicts, SWS will work to resolve them before merging the work.
  4. When the work passes review, the work will be merged and deployed during the next release. Please note that when we stage work for review for a release, we will deploy also to the dev and sandbox site. Any work done there will be wiped out.
  5. The work will be QAed as part of the QA we will be doing for the release
  6. If it passes QA, it will be merged onto the multisite. Once this happens, the work will be available on all sites on the stack.

Process for capturing configuration

General steps for how we envision the config capture process to work.

  1. Check the configuration sync page.
    1. /admin/config/development/configuration
    2. This will let you know if there are any changes made to configuration that differ from the codebase. Sometimes there are false positives where no configuration changed, just the lines of the configuration file.
    3. If there are changes, you can quickly backup those changes with an export.
  2. (optional) Backup current changes
    1. /admin/config/development/configuration/full/export
    2. Export a .zip file of the current configuration as a backup and store it if needed later.
  3. Re-import configuration
    1. /admin/config/development/configuration
    2. Import the configuration files in the codebase by clicking the "Import All" button. This will "reset" the state of the configuration to match what is in the codebase, and ensure we only capture the changes being made now.
  4. Make changes on the site.
    1. Make the config changes you want to make. Try to limit the changes to the scope of one ticket at a time, maybe more if it makes sense.
  5. Export the configuration
    1. /admin/config/development/configuration/full/export
    2. Export a .zip file of the current configuration with changes in place.
  6. Rename the .zip file to match the following convention:
    1. <ticket-number>--<few-word-summary>-<y-m-d-date>.tar.gz (e.g., SDSS-123--update-event-node-2023-02-16.tar.gz)
    2. Add the zip file to the ticket
  7. Re-import configuration
    1. Re-import the configuration files in the codebase by clicking the "Import All" button. This will "reset" the state of the configuration to match what is in the codebase, and ensures our changes won't linger on the site for whoever makes changes in the future.
  8. Create a PR with the configuration changes
    1. IMPORTANT: This assumes knowledge of git and access to repo. These changes can be handled by a developer as long as they are given the .zip file with the configuration changes and proper context.
    2. In the cloned ace-sdssgryphon repo create a new branch for your changes.
    3. Delete all the files in this directory
      1. docroot/profiles/sdss/sdss_profile/config/sync
    4. Extract the .zip with configuration changes to the same directory
      1. docroot/profiles/sdss/sdss_profile/config/sync
    5. Commit changes, push up, create a PR, fill out PR template, and assign it to an SWS developer

Conventions

The following conventions should be followed to make it easier to identify elements built by SDSS web editors, trace errors, and avoid code conflicts.

Naming conventions

  • Names should be generalized (For example "Fellows" rather than "Institute Fellows".)
  • Names should be readable, 
  • Machine names for fields, views, and vocabularies should be prepended with "sdss_custm_."  

    The su_ prepend is enforced by default, which allows us to identify configuration that comes from Stanford development, rather than from contributed or core modules. The additional sdss_custm_ will help us identify configuration that needs to be captured from our development site. Example: su_custm_my_view_name

Permission

  •  Please remember to allow new content types and taxonomy terms to be used by Administrators, Site Managers, and Site Editors
  • Use the permissions form with the content type OR taxonomy. Changes to the permissions overview will not get saved.