Use custom Drupal modules

1. Back up the Dev site. On the Pantheon dashboard for the site, select the Dev tab, then choose  "Code" on the left and  make sure Development Mode is set to Git. Then chose Backups from the list on the left, click on the yellow button "Create New Backup".
2. Back up the Live site if changes have been made since last night's backup. On the Pantheon dashboard for the site, select the Live tab, then chose Backups from the list on the left, click on the yellow button "Create New Backup".
3. Clone the Live site to Dev. On the Pantheon dashboard for the site, select the Dev tab, then choose Database / Files from the menu on the left.  Choose the Live environment, and make sure all 4 boxes are checked: Clone Database, Clone Files, Run update.php, Clear Caches. Wait for the workflows to complete.
4. This step is optional. It stages any config changes that are in the database because of changes you have made to things, such as views, that appear in the config file. It is okay not to integrate such changes so long as you are doing all of your content updates in the live environment.
   1. Place Pantheon in SFTP mode for the Dev site: On the Pantheon dashboard for the site, select the Dev tab, then chose Code from the list on the left, and click on SFTP next to Development Mode.
   2. Visit the Development Site and sign in. From the Administration menu, go to configuration-development-configuration synchronization. Click on the Synchronize tab. If anything is listed there it means there have been some changes to config. If there are none to apply, you can go on to preparing the local repository.
   3. Click on the Export tab, and then click on the Export button, and save the exported file to your computer. 
   4. Click on the Import tab, still in the configuration-synchronization menu, and upload the file you just created. If you see a red warning message "The directory .../config is not writable" it means that you forgot to place Pantheon in SFTP mode. Go back and do that then come back and import the file.
   5. Commit the changes in Pantheon. On the Dev tab, you should see the changes waiting. If you don't, try refreshing the browser. Give them a name that describes what the changes are, e.g., "change the Obits Search view", then commit. Switch the Development environment back to GIT mode.
   6. Clear the Pantheon caches: click on the "Clear Caches" button in the top right area of the page, and wait for the process to finish.

Clone the site Git repository (the development version) from Pantheon to your local machine. Note that you must have generated an SSH key and added it to Pantheon in order to clone. 

1. Copy the code revealed by the “Clone with Git” button on the site’s Pantheon page – the “Code” page. 
2. Open a Git command window, set directory to the root of where you want the clone to be, e.g. type “cd c:/Webspark2” at the command line
3. Paste the Pantheon command onto the next line and hit enter. Wait for the process to complete.

1. In Visual Studio Code, from the File menu, choose "Open Folder" and select the desktop folder that contains your repository, e.g. Webspark2. On the left in the "Explorer" section you should see the files in that folder.
2. Click on the composer.json file that is in the custom-dependencies folder. you should see the contents of that folder in the right-hand window. Modify the contents of the "require" section of that file as needed to add modules, update versions, or delete modules:
   1. For a new module, add a line. The order of the modules listed under "require" is not important. Find the correct information for the line on the Drupal site for the module. Your entry will be of the form “drupal/module-name”: version. You can find the needed language on the module's page in Drupal (drupal.org/project/module-name, where module-name is the name of your module). It is at the bottom, under Releases. Be sure to select the version that works for the version of Drupal currently installed with Webspark 2.
      
      If the Drupal version that is listed for the module is newer than that currently being used on our sites, find an older version by clicking on "View all releases" at the very bottom of the module's page.
   2. For updates, replace version number in the line for the updated module with the newer version.
   3. For removals, delete the module's line.

3. In Git or your terminal command software, change to the root directory of the local repository that you just copied down from Pantheon: type “cd [repository location]”, e.g. cd c:/Webspark2/asura3” in the command line. 

    

4. Type “git status”. You should see the the file custom-dependencies/composer.json listed. If you don't or if you see any other files, you may need to start over -- something has gone wrong.
5. Type “git add custom-dependencies/composer.json”. 
6. Type “git commit –am “change description”, where "change description" is your description of the change, for future reference. This will package the files and identify the change when it is made on Pantheon.
7. Type “git push origin HEAD”. Note the capitalization of the last word -- it is important. This will apply the update to the Dev environment of the site.
8. Pantheon will commit the change and it to the commit log using the name you supplied in the git commit command.
9. Clear the Pantheon caches: click on the "Clear Caches" button in the top right area of the page, and wait for the process to finish.

Check for required module libraries

On the development site, from the Administrative menu choose Reports, Status report. If you see an error for an installed module that says "not installed" or "not found", you need to install the associated library.

The following instructions probably will not work, because the library is not pushed forward to test and live environments. You cannot install them directly in the test and live environments, as permissions prevent you. So, you may have to get help from Enterprise Technology if you have this situation.

Required application for installing a library

You will need to have WinSCP, which is a free application for Windows that you can use to work with SFTP files that are on a server. You will also have to add your computer's SSH key for Pantheon to WinSCP.

To install a library

1. The error message in the status report will have a link for downloading the library to your computer. Click on that, then click on the Zip file to extract it. Delete any example folders from the extracted files.
2. In Pantheon, from the Code menu on the left, make sure that the Development Mode is set to SFTP .
3. Click on the Connect with SFTP button to the right of the Development Mode toggles, and then click on the Open SFTP Client button.This will begin a WinSCP session. 
4. In the right-hand window of WinSCP, click on the Home icon at the top, then the code folder, the web folder, and the libraries folder. Note that you can navigate up and down in the folder structure using the blue arrow icons.
5. Refer to the Status report message to determine the name of the folder within the libraries folder that you will need. An example message says, "The Colorbox library needs to be downloaded and extracted into the /libraries/colorbox folder in your Drupal installation directory." If your message doesn't specify the folder, it probably is the same as the module name.
6. Right-click in the open space of the libraries folder listing in WinSCP and choose New-Directory. Enter the name of the directory you need. Then open that directory
7. In the left window of WinSCP you will see your computer's files. Navigate to the extracted library contents for your module, Select all of the contents, and drag them to the new folder on the Pantheon server.
8. Return to the status report on your development website, and refresh the browser. The error messages should be gone.

Synchronize the updates in the Dev environment and test

1. Optional: Visit the development site. From the Administration menu, go to configuration-development-configuration synchronization. Click on the Synchronize tab. If there are any changes listed, use the export-import procedure to apply them, as in the item above "prepare the site". There will not be any if you prepared the database as indicated above. However, if you didn't, It is possible that you will have to do this more than once to sync all of the changes. Note: the new module(s) will not result in config changes until you configure them.
2. Clear the Pantheon caches: click on the "Clear Caches" button in the top right area of the page, and wait for the process to finish.
3. Test the new module in the Dev environment. To do so, enable it and configure it following instructions found for the module on Drupal.org. Review the site pages to make sure everything works as it should. Enabling is done by finding the module in the Extend tab of the administrative menu, then clicking on the box next to it. If you see problems, you may want to restore the Dev site from your backup.
4. Optional: If you did any module configuration, including permissions, repeat the export-import steps listed under "prepare the site". 

Apply the updates to the Test environment

1. Go to the Pantheon dashboard for the site, and chose the Test tab.

2. On the left, click on Deploys. You should see your changes waiting. Make sure the buttons for cloning database and files are checked, enter a description, and then click on Deploy. 

    

3. Again, make sure everything looks okay on the test site web pages. If you want to see the new module working in the test site, you will need to enable it here. Stop here if you see problems. Review your steps. 

Apply the updates to the Live environment

1. Go to the Pantheon dashboard for the site, and chose the Live tab.
2. On the left, click on Deploys. You should see your changes waiting. Click on Deploy. This is shown as step 5 on the overview diagram.

3. Clear the Pantheon caches: click on the "Clear Caches" button in the top right area of the page, and wait for the process to finish.

    

4. Enable and configure the new or changed module(s).
5. Again, make sure everything looks okay on the live site web pages. There should not be any issues if you have checked the Dev and Test sites before proceeding, and stopped if there are problems. If, however, you see problems on your live site, you can restore from the backup you created before beginning this process.