sfgov

Local Development Setup

Prerequisites

• Latest version of Lando installed.
• A global installation of Composer*

Instructions

1. Get the codebase: git clone git@github.com:SFDigitalServices/sfgov.git. Note: Always use the Github repository for development. CircleCI is used to deploy an artifact build to Pantheon via Github.

2. Go to the root directory. cd sfgov

3. Download the following assets from files(_dev)/private/saml on Pantheon via SFTP or the Backups tab on the dashboard. Place them in web/sites/default/files/private/saml:

   IDCSCertificate.pem
   metadata/
   saml.crt
   saml.pem
   simplesaml_config.php

4. Install Composer dependencies and execute post-install scripts (including copying saml related things above to the right vendor directory): composer install

5. Start the Lando VM: lando start

6. Obtain a machine token from your Pantheon dashboard, and run the provided command, making sure to prefix it with lando, e.g. lando terminus auth:login --machine-token=TOKEN

7. Get latest DB and files from Pantheon dev environment: lando pull. Most of the time, code will not need to be pulled from Pantheon: lando pull --code=none --database=dev --files=dev.

8. Create a local services file:

   Copy development.services.yml

   cp web/sites/development.services.yml web/sites/default/local.services.yml

   Enable Twig Debug mode (optional) in local.services.yml

   parameters:
     # Add Twig config below "parameters".
     twig.config:
       debug: true
       auto_reload: true
       cache: false

9. Create a local settings file, and add the settings below:

   Copy example.settings.local.php

   cp web/sites/example.settings.local.php web/sites/default/settings.local.php

   Add the following to settings.local.php

   # Point to your local services file:
   $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/default/local.services.yml';
   
   # Add a dummy hash salt.
   $settings['hash_salt'] = 'whatever';
   
   # Database settings.
   $databases['default']['default'] = array (
     'database' => 'pantheon',
     'username' => 'pantheon',
     'password' => 'pantheon',
     'prefix' => '',
     'host' => 'database',
     'port' => '3306',
     'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
     'driver' => 'mysql',
   );

   See Disable Drupal 8 caching during development for more details.

10. Add drush configuration file /drush/drush.yml (Optional)

    options:
      uri: 'https://sfgov.lndo.site/'

11. Update dependencies and active config in the following order:

    # 1. After updating the codebase, install any pending composer dependencies.
    lando composer install
    
    # 2. If any dependencies were updated, run database updates.
    lando drush updb -y
    
    # 3. Update active config to include and changes pending in `develop`.
    lando drush cim -y
    
    # 4. Build the theme assets. (@see theme readme for prerequisites.)
    cd web/themes/custom/sfgovpl
    npm ci
    npm run build
    
    # 5. Clear the cache.
    lando drush cr

12. Visit https://sfgov.lndo.site. 🎉

Pull Request Workflow

https://pantheon.io/docs/guides/build-tools/new-pr/ https://gist.github.com/Chaser324/ce0505fbed06b947d962 https://www.atlassian.com/git/tutorials/making-a-pull-request

TLDR version:

1. Create a branch from develop and make changes. Push branch.
2. Open a pull request to merge from branch to develop.
3. The team reviews, discusses, and makes change requests to the change. This includes the PM reviewing the CircleCI review app BEFORE it is merged into develop.
4. Change is approved and merged.
5. Delete branch.

Adding a contrib module

1. Create a new branch git checkout -b new_branch
2. Install module with composer composer require drupal/paragraphs
3. Update the lock file hash composer update --lock
4. Enable the module lando drush -y en paragraphs
5. Export config lando drush -y cex
6. Check in modified composer and config files git add composer.* config/*
7. Commit and push changes git commit -m 'installed paragraphs' && git push
8. Wait for CircleCI to build and deploy to a multidev. CircleCI will add comment to the checkin on GitHub with link to the created MultiDev.
9. Create Pull Request and merge to develop
10. Switch away from branch and delete branch git checkout master && git push origin --delete new_branch && git branch -d new_branch

Local Behat Tests

For additional context, refer to config in .lando.yml.

lando behat --config=/app/tests/behat-pantheon.yml --tags sfgov

Updating core with Composer

PHP out of memory issues can occur when running updates with Composer. Drupal documentation suggests the following command, which will disable the memory_limit:

php -d memory_limit=-1 `which composer` update drupal/core --with-dependencies

then

lando drush updatedb
lando drush cr

* I'm not 100% sure, but I don't think global composer is necessary. One can use lando composer install instead. -ZK

PHP Codesniffing

To run PHPCS use lando php-sniff path/to/directory To run PHPCBF use lando php-fix path/to/directory

Standards and rules for codesniffing can be edited in phpcs.xml at the project root.