Developing for Drutopia¶
This document covers writing code for and contributing configuration to Drutopia features and the Drutopia distribution.
Drutopia so far consists of four bodies of code:
- Drupal 8 core.
- Drutopia features (Drutopia Article, etc.).
- Drutopia install profile (drutopia).
- Contributed Drupal modules and themes:
- Configuration Update Manager
For introductions on using GitLab, see:
To post suggestions or bug reports, use the issue queues for the GitLab projects linked above. See the GitLab documentation on creating an issue.
Geting set up with Git and GitLab¶
To get started contributing code-level changes to Drutopia features or the Drutopia distribution, see the GitLab basics documentation page for tips.
You will need to:
Local development environment setup¶
There are many possible ways to set up a local development environment. These instructions will assume a basic LAMP (Linux, Apache, MySQL/MariaDB, PHP) setup. For more information, see the drupal.org documentation on setting up a local development environment. See also the drupal.org page on where to look for support.
Download and install Composer¶
Composer is a dependency manager for PHP. It manages core dependencies for Drupal Core and we use it for the same purpose with Drutopia.
composer create-project drutopia/drutopia_dev_template:dev-master --no-interaction drutopia-dev
- Visit your site and follow the Drupal installation instructions.
- Log into your new site and install the modules needed for development. These include:
- All Drutopia feature modules (which are listed on the modules page under the heading “Drutopia”).
- Features UI and its dependencies (Features and Configuration Manager Base).
Work on an issue¶
Improvements or fixes should have an accompanying issue in one of the GitLab project issue queues.
- Before you begin, ensure you have committed any changes made for a previous issue, since you’ll be reverting your site and otherwise may lose those changes.
- If no GitLab issue exists, create one. If one does exist, make sure it’s assigned to you.
- For each project in your local dev site, first make sure you’re working with the latest code.
- The install profile lives at
profiles/contrib/drutopiaand each of the feature modules at
- Check out the development branch.
git checkout 8.x-1.x
- Pull in any changes from the origin:
git pull --rebase origin 8.x-1.x
- Ensure your site reflects the latest code base. You may do this by reinstalling, or by using Drush to restore the site features to their default state. Warning: you will lose any uncommitted changes you’ve made. From the site’s directory, type:
drush features-import-allor, if you are sure you don’t want to review the changes you’re losing,
drush features-import-all -y
- For each project you’re going to be working on, create a new branch to work on the issue. A branch like this is often called a feature branch. Here is an example for an issue on the Drutopia Site project to enhance the default admin toolbar, where 10 is the issue number.
git checkout -b 10-admin_toolbar
Make and export the changes¶
For each feature you’re working on, make sure you’re working with the latest code.
git pull --rebase origin 8.x-1.x
On the local development site you installed, make the changes required to resolve the issue. This might involve downloading and installing new modules and/or making configuration changes.
Now navigate to the Features admin page and regenerate the feature or features you’ve worked on. See the Features module documentation on generating features. Regenerate the feature. You will need to delete the previously exported version of the feature and replace that with the new export–making sure you don’t delete the Git information in a
Creating a new feature¶
We encourage proactive contributions to Drutopia, though it could be helpful to check in with the team about your feature idea.
We determine if a feature is included in Drutopia Base, or in a more specific distribution based on whether the majority of Drutopia user would benefit from the feature. The final call on this can be made by any technical lead.
If you are creating a new feature:
- Create a new project for the feature on GitLab in the drutopia group.
- Clone the project locally.
- On the site where you’ve done your development, navigate to the Features admin page and generate the feature to package up the configuration you’ve worked on. Start by editing the configuration for the features bundle assignment plugins.
- Generate the feature and copy its files to the directory where you cloned the repository. For example, if the repository is in a directory called
drutopia_example, you will end up with a file
- Create a
composer.jsonfile for the feature. If your feature depends on other Drupal modules, add those dependencies to the composer file’s
requiresection. You can use an existing Drutopia feature’s composer file as a model.
- Add and commit the files, making sure you’re creating a new
8.x-1.xbranch before committing:
git checkout -b 8.x-1.x
git add .
git commit -m "Initial commit of Drutopia Example feature.
git push origin 8.x-1.x
Registering your new feature¶
- Create a new project on drupal.org:
- uncheck the option to include an issue queue
- for project home page, enter the GitLab project URL
- assign the user ‘drutopia_gitlab’ the permission “Write to VCS”
- assign the users mlncn and nedjo (optionally rosemarymann and cedewey) full rights to the project
- push the 8.x-1.x branch
- create a dev release for the 8.x-1.x release
- edit the project to set 8.x-1.x as the default branch
- administer releases to set 1 as the recommended major version
- Edit drutopia_projects.txt file in https://gitlab.com/drutopia/hackysync to add the new project.
- Create a new project on GitHub (mlncn)
- Edit the
composer.jsonfile in the Drutopia install profile to include the new feature.
- Edit the
composer.jsonfile in the Drutopia SDK to include the new feature.
- Edit the
composer.jsonfile in Drutopia VM to include the new feature.
- Edit the file
drutopia.subprofiles.ymlin the Drutopia project to add the new feature to the subprofiles.
Add or update code dependencies¶
If you added any new code dependencies like modules or themes to the feature you’re working on, or if you need to update to a new version of those dependencies or of Drupal core, you will need to add these changes to
composer.json files. These files are used by Drutopia developers.
Updating Drupal core¶
To update to a new release of Drupal core:
- Edit the value for
composer.jsonfile in the Drutopia repository.
Adding or updating contributed modules and themes¶
First, determine if the module or theme you’re adding or updating is specific to a given Drutopia module (for example, adding the Admin Toolbar module to the Drutopia Site module). If so:
- Edit the module’s
composer.jsonfile, adding a section for a new module or theme or changing the version number for an existing one.
Commit your changes¶
Once you have completed the changes, you can commit them to your local code base. Note that you may need to follow these steps in more than one project. For example, you may have added a field storage to the Drutopia Core module and added the corresponding field to a second Drutopia module.
- Review what changes have been made. This command will list off changed, added, or deleted files.
$ git status
- Add the changed, added, or deleted files.
$ git add -A
- Commit your changes and push them to GitLab. In this example,
10-admin_toolbaris the name of the feature branch we’re working in.
$ git commit -m "Issue #10: add Admin toolbar." $ git push origin 10-admin_toolbar
Before starting more development, get up-to-date with::