This guide contains information to help onboard developers to work on the Acquia integration, hereafter referred to as "the plugin".
After reading through it the developer should understand:
- The high level goals of the integration
- The general features roadmap
- How the plugin is structured
- How additional services containers are added
- How additional tooling is added
- How the project is tested
- Where framework level overrides live
- Contributing code
It may also be valuable to review the user documentation for this integration as that provides a bit of a Specification as Documentation.
The high level goals of the integration are straightforward:
This allow users to run their Acquia projects locally using the same images, build processes, configuration, etc as they do on Acquia itself. This means that a Landofile using the acquia
recipe can be be something simple like this:
name: lando-acquia
recipe: acquia
The implication here is that Lando will instead look and use the acquia
configuration files, including its docker-compose
files instead of its own mechanisms. You can, however, still use the Landofile for additional power you may need exclusively in the local context.
As you have probably noted, Lando does the above OOTB so this should not be a huge challenge. The value add that Lando provides here is basically simplying the onboarding and spinup process and standardizing that flow across os, projects, etc.
TBD
TBD on how we want to do this.
RTFM if you need more info on dat.
We have currently secured funding for the first phase of the roadmap but we still need to fund phases two and three.
The tentative roadmap for acheiving the above is
- An alpha quality release that covers sections 1. and 2. in the overview.
- This release is scheduled to be an "internal alpha" but it may be ok to cast a wider net as long as the alpha part is understood.
- A user should be able to
lando init
a cloned downacquia
Drupal 8/9 git repo that is properly configured for use with Lando and get it running - Popular Drupal services like
mariadb
,mysql
,memcached
,redis
,solr
,postgresql
andvarnish
are expected to work
These are all expected to be delivered at alpha
level quality eg the 80/20 rule for use case coverage is probably a good quality threshold.
- TBD
- TBD
- TBD
This plugin follows the same structure as any Lando plugin but here is an explicit breakdown:
./
|-- lib Utilities and helpers, things that can easily be unit tested
|-- recipes
|-- acquia The files to define the `acquia` recipe and its `init` command
|-- services Defines each Acquia service eg `solr` or `php`
|-- test Unit tests
|-- types Defines the type/parent each above service can be
|-- app.js Modifications to the app runtime
|-- index.js Modifications to the Lando runtime
TBD
It's easiest to develop by spinnning up the Acquia D9 example directly in the Lando codebase
# This assumes you have already installed lando from source and are in its root directory
cd examples/drupal
# Spin up one of your Acquia Sites
rm -rf drupal && mkdir -p drupal && cd drupal
lando init --source acquia --acquia-key "$ACQUIA_API_KEY" --acquia-secret "$ACQUIA_API_SECRET" --acquia-app "$ACQUIA_APP_ID"
lando start
TBD
This is going to be a lean and agile project where user feedback drives development. For example a user is going to try it out and say "cool, but what about solr", Amazee will add support for Solr to the relevant example repos, let us know, and then we will add support/tests for solr in Lando.
Its best to familiarize yourself with how Lando does testing in general before proceeding.
Generally, unit testable code should be placed in lib
and then the associated test in tests
in the form FILE-BEING-TESTED.spec.js
. Here is an example:
./
|-- lib
|-- stuff.js
|-- test
|-- stuff.spec.js
These tests can then be run with yarn test:unit
.
Func tests are made by just adding more entries to each examples README. This uses our made-just-for-Lando testing framework Leia. See below for our current acquia tests:
These are then run by GitHub Actions. While you can run all the func test locally this can take a LONG time. If you decide you want to do that we recommend you generate the test files and then invoke the tests for just one example.
# Generate tests
yarn generate-tests
# Run a single examples tests
yarn mocha --timeout 900000 test/acquia-drupal-9-example.func.js
WIP but outline is
- GitHub flow as normal eg branch for an issue -> PR -> merge
- Lets review all Acquia PRs together for awhile: this should keep us on the same page and also force knowledge transfer
- Lets definitely be updating the user docs/dev docs
- Once we have the d8 and kitchen sink example func tests lets also be adding tests on every commit
- Lets wait on unit tests until things settle down a bit but a good rule of thumb is try to put things we would want to unit tests in
lib
somewhere.