mglaman / midcamp

MidCamp D8 site

MidCamp

The Drupal website for midcamp.org

Getting access

Ensure you have an Amazee account with your SSH keys loaded. If not reach out on the MidCamp Slack in #website-amazeeio.

DDEV-mode

Prerequisites

• DDEV

Getting started

Refer to DDEV's documentation for detailed information on configuration, customization and troubleshooting.

1. Start your local environment with ddev start
2. Run ddev auth ssh to load your ssh keys.
3. Import your local database and files via:
   1. ddev pull lagoon
   2. Skip files/db with --skip-files or --skip-db

GitPod-mode

.gitpod.yml adds support for developing in a fully web-based environment called GitPod. GitPod doesn't have a great solution for forwarding ssh keys yet, so in order to be able to pull from Amazee you have two options:

1. [Add your existing SSH keys to GitPod (if you trust them)]gitpod-io/gitpod#666 (comment))
2. Generate a new key pod and give it to Amazee - you'll have to do this on every new instance, but Amazee will recognize new keys basically instantaneously, so it isn't too bad.

• Rock and roll

Lando-mode

Prerequisites

• Lando (tested and working with version v3.0.23)

Getting started

Refer to Lando's documentation for detailed information on configuration, customization and troubleshooting.

1. Start your local environment with lando start
2. Import your local database and files via:
   1. lando get-db
   2. lando get-files

Working with Lando

Some common Lando commands to be aware of:

• lando start starts your application
• lando stop stops your application
• lando poweroff stops Lando and any Lando apps currently running
• lando restart restarts your application
• lando rebuild rebuilds your application and re-runs any build steps
• lando info displays information about your local application, including relevant ports and connection info

All relevant tooling is included within the project containers, and as a result you can run all of this tooling from outside the containers by prefacing your commands with lando , for example:

• lando composer require drupal/pathauto
• lando drush cache-rebuild
• lando npm install

Git workflow

When beginning work on a task, start a new branch:

git checkout -b feature/my-great-work

Amazee workflows will build a new environment for every branch that begins with feature/ when it's pushed to GitHub. In order to access the environment for the branch above, visit https://nginx-midcamp-org-feature-my-great-work.us.amazee.io/. Databases for that environment are synced from Amazee dev, and it takes a few minutes after Circle completes for the install to complete.

Deploying

To deploy a feature:

• merge your feature branch into master,
• (optional but plz) give it a few minutes to sync, then test your work on https://dev.midcamp.org/
• merge master to production.

See deploy_tasks in .amazeeio.yml for what happens after deploy (updb, cim, and more!)

How do I Drupal?

The Drupal root

This project uses Composer Installers and Drupal Composer Scaffold to assemble our Drupal root in web. Dig into web to find the both contrib Drupal code (installed by composer) and custom Drupal code (included in the git repository).

Adding modules

• Download modules with composer: lando composer require drupal/bad_judgement:^8.1
• Enable the module: lando drush en bad_judgement
• Export the config with the module enabled: lando drush config-export
• Commit the changes to composer.json, composer.lock, and conf/drupal/config/core.extension.yml. The module code itself will be excluded by the project's .gitignore.

Working on the theme

As of 2019, component markup, styles and interactivity all live in the Hatter Styleguide The majority of theming work will occur in that repository and instructions are included in the readme.

The compiled assets are packaged as an npm dependency. To install the latest, run lando npm install either in the root of this repository, or the theme directory. The initial setup process, along with the build process will install these dependencies as well.

To update to the latest version of the Hatter Styleguide, change to the theme directory and run lando npm update @midcamp/hatter Commit the resulting updates to package.json and package-lock.json

To include a specific version of the Hatter styleguide, update the version of the hatter dependency in package.json in the related theme and them run lando npm install

Local Drupal theme development

To streamline theme development in the context of Drupal, you can use NPM's link feature.

First, in your local clone of the Hatter design system (hatter-v2) run:

• npm link

You'll only need to run this command once in the Hatter repository unless you remove or reinstall the package.

Then, in the Drupal theme directory (web/themes/custom/hatter_2019 for example,) run:

• lando npm run watch-hatter

This will link the Hatter package to your local development version of the pattern library, and watch for any changes.

When you're done with local theme development, run the following script to unlink your local version of Hatter and re-install the published version of the package.

Patching modules

Sometimes we need to apply patches from the Drupal.org issue queues. These patches should be applied using composer using the Composer Patches composer plugin.

How do I run tests?

• lando behat
• lando phpcs features/bootstrap web/modules/custom
• lando phpmd web/modules/custom text .phpmd.xml
  • This should be configured to show the same errors triggered by Code Climate that you see on the Pull Request.

Troubleshooting

Be sure to visit Lando's troubleshooting page.

If your local development environment is behaving unexpectedly, you may need to do restart, reinstall, or rebuild your application. Try the commands below in order, the fastest/lightest options are at the top.

Command	Description
lando restart	Restarts the app, preserving container state
lando install	Clean Drupal install
lando rebuild	Restarts the app, preserving data but not state
Restart Docker	Can sometimes help build steps that time out
lando destroy	Destroys the app, preserves data
rm -rf ~/.lando	Clears your Lando cache

Amazee.io Drupal Docker development environment

If you are still using the old tooling from Amazee, please refer to the legacy documentation