First off, thanks for taking the time to contribute to AZ Quickstart!
AZ Quickstart is created by Arizona Digital, a team of web-focused volunteers that meet weekly to create projects like Arizona Bootstrap and Arizona Quickstart.
- A GitHub account.
- Slack is our main source of communications.
- Use the
#ua-quickstart-d8channel for questions/comments related to this project. - Use the
#friday-meetingschannel to ask questions or get updates related to Arizona Digital meetings, both physical and via Zoom. - Use the
#uadigital-generalchannel to ask general questions related to Arizona Digital.
- Use the
- A basic understanding of Git.
- Local containerized (Docker) dev environment tool either lando or ddev
- An IDE with the capability to attach to a remote codeserver or docker container. Visual Studio Code allows for this.
If you found a security vulnerability and it's related to Drupal core or a Drupal contrib module, please follow these instructions.
If it's a security issue related to az_quickstart code, please email us here:
[email protected]
We use GitHub Issues to keep track of issues and bugs.
If you don't see the specific issue or bug after looking at the AZ Quickstart Project, please create a new issue with proper description of bug or details related to new feature request.
We follow Drupal coding standards.
First, make sure there is an issue associated with your pull request.
Use proper branch naming conventions based on your issue type:
feature/<issue-number>bug/<issue-number>
So, bug fix for issue #123 would be on branch bug/123
Create a draft pull request if you'd like to run automated tests and/or get feedback before your pull request is completely ready for review.
Note: Probo will build a Drupal site with the committed changes and an admin
user with username and password azadmin.
Follow the pull request template and use proper formatting for commit messages:
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- When only changing documentation, include [ci skip] in the commit title
- Use
fix/close/resolvekeywords in commit messages to close associated issues
Add new feature X...<at most 72 characters>
Closes #123 by creating y and z. This can be a paragraph of explanation.
To create a local copy of az_quickstart and build a working Drupal 8 site from it, use the following commands.
Important: The Drupal code base will only be created inside the lando/ddev
container, so if you want to see the code use lando ssh or ddev ssh to ssh
into the container, or follow the instructions below for accessing code via
Visual Studio Code.
Note: The Lando and DDEV installs create an admin Drupal user with username
and password azadmin.
git clone https://github.com/az-digital/az_quickstart.git foldername
cd foldername
lando start
lando install
git clone https://github.com/az-digital/az_quickstart.git foldername
cd foldername
ddev config --project-type php
ddev start
ddev install
Note: Use ddev pause and ddev start to restart the container.
Using ddev restart will require a re-install with ddev install.
Since the codebase you'll be editing exists inside the lando or ddev docker container, you may need to use an IDE to edit code, especially if you don't want to ssh into a docker container and use nano, or rsync code from local into the docker container 100 times.
Note: These instructions may not work for DDEV.
Setup:
- Make sure you have Visual Studio Code installed,
- Install the Visual Studio Code Remote Development Extension Pack
- In the Command Palette,
which can be found in View menu or (⌘⇧P on Mac) type
Remote-containers: Attach to Running Container...and click on the result to bring up a list of running containers. - If using lando, find the container whose name ends with
_appserver_1. Click it to attach to that container. - The last thing you'll have to do is add a folder from within the container
to your workspace.
To do this, use the file menu within Visual Studio Code,
to Add Folder to Workspace.
Then replace
/rootwith the/appfolder. - You are ready to begin development.
Notes: Visual Studio Code has git integration, so you can use that to create new branches and push up to github. Visual Studio Code can automatically add the app folder to your workspace through Attached Container Configuration Files, which are created for you automatically by Visual Studio Code.
As a general rule of thumb, Arizona Digital has a goal of having unit, functional, or kernel tests for all parts of AZ Quickstart. This goal is meant to ensure that committed code works in perpetuity, without unexpected bugs after merging new code. We run tests on every pull request, but it is often up to each individual contributor to write tests for their new code.
Here is a rudimentary guide to running tests on your code with a local development environment like Lando, or DDev.
When you install either of the recommended environments with the configuration provided by this project, you will have our testing environment built in, but it can still be a bit complicated.
PHPStan focuses on finding errors in your code without actually running it. It catches whole classes of bugs even before you write tests for the code. It moves PHP closer to compiled languages in the sense that the correctness of each line of the code can be checked before you run the actual line.
lando phpstan
ddev phpstan
With lando running and quickstart installed and the branch with the changes you want to run tests on checked out.
Steps for running phpunit tests on the Quickstart installation profile.
git clone https://github.com/az-digital/az_quickstart.git azqs-71
cd azqs-71
git checkout -b feature/71
lando start
lando phpunit
git clone https://github.com/az-digital/az_quickstart.git azqs-71
cd azqs-71
git checkout -b feature/71
ddev config --project-type php
ddev start
ddev phpunit
Much of the content editor experience for pages in Quickstart consists of constructing pages using paragraph items as content building blocks. In crafting new paragraph types, it will often be necessary to include settings that are tracked as part of individual paragraph items that control the display of the related paragraph item. The recommended approach for including this sort of setting is with Paragraph Behavior Plugins.
This allows developers to attach Form API elements to the paragraph form and handles saving this configuration on a per-paragraph basis.
The interface for Paragraph Behavior Plugins is located here.
If you wish your Behavior Plugin to also incldue the standard Quickstart paragraph behaviors, extend AZDefaultParagraphsBehavior.
Note that by default, Behavior form elements are shown on a Behavior tab on the paragraph. This can be avoided currently by a workaround. There will likely be a more official paragraphs API for this in the future.
This project uses an ES6 to ES5 transpile process similar to Drupal core.
This means that you should only update .js files named .es6.js and should
never manually edit files named .js as these are machine-generated.
This can be done on demand with yarn build, or in response to changes
with yarn watch. When in watch mode, javascript files will be transpiled as
they are updated.
lando yarn build
OR
lando yarn watch
ddev yarn build
OR
ddev yarn watch
You may run eslint to lint javascript in local development with one of the following two commands.
All files:
lando eslint .
ddev eslint .
Single file:
lando eslint myfile.js
ddev eslint myfile.js
Developing within Drupal can be a real challenge without debugging enabled.
Devel and Drupal Console are both included in the development metapackage that is downloaded when installing a site locally via Lando, or DDev.
You can easily enable them by using the following commands.
Quickstart provides Lando tooling for enabling theme debugging.
Simply use the following command once your site is installed:
lando theme-debug
Quickstart provides DDev tooling for enabling theme debugging.
Simply use the following command once your site is installed:
ddev theme-debug
A question that frequently arises for Quickstart contributors is whether a change that they are making requires a database update or if configuration file changes are sufficient.
az-digital/az_quickstart is a Drupal distribution that is hosted on many different platforms by a variety of teams employing different strategies and cadences when it comes to updating their Quickstart websites. This necessitates relatively strict guidelines that should be followed by the Arizona Digital team when making changes to Quickstart itself.
Configuration changes will require database updates if:
- Your code adds a new setting that never existed before.
- You are changing a default setting and it would be best for it to be the new default on sites immediately, regardless of downstream decisions.
- Your code replaces an existing setting and has a new key name.
Configuration changes will not require database updates if:
- Your code adds another option to an existing setting and doesn't need to be selected by default.
- Your code changes an existing setting, but doesn't have breaking implications if configuration updates aren't applied right away downstream.