Development guide for the Drupal 8/9 connector

1 Managing issues
2 Code reviews
3 Local development setup
- 3.1 Useful bash aliases
- 3.2 Pre-commit hooks
- 3.3 Setup scripts
- 3.4 Testing with ngrok
4 Running Tests
- 4.1 Locally
- 4.2 Running Javascript tests
- 4.3 On Drupal.org
5 Adding tests
- 5.1 Adding upgrade tests
6 Creating patches
- 6.1 Creating only-test patches
- 6.2 Creating interdiffs
- 6.3 Working with feature branches
7 Manual QA
8 Commits
- 8.1 Giving credit

Managing issues

All issues must exist on drupal.org. In the Jira issue we will add a link to the Drupal.org issue.

For creating issues, please use the issue template. Dreditor will add a button for doing that, so install Dreditor at https://chrome.google.com/webstore/detail/dreditor/dhdpoembhlojpmehepeadblhglloobao

Code reviews

Use dreditor for inline commenting on patches. This helps keeping track and referencing reviews.

Local development setup

TBD

Useful bash aliases

TBD: make this into a composer package or commit to the repo.

alias setupenv='COMPOSER_DISCARD_CHANGES=true composer install --no-interaction && drush site-install demo_umami --yes && drush en lingotek --yes && drush en simpletest --yes && drush php-script setup.php'

alias runtest='php core/scripts/run-tests.sh --color --url http://lingod8.test --verbose --class $1 $2'

Pre-commit hooks

TBD: make this into a composer package or commit to the repo.

Setup scripts

TBD: make this into a composer package or commit to the repo.

Testing with ngrok

Option 1 (preferred)

If you use ddev, just run

ddev share

Option 2 (not ddev, more complex, incomplete docs)

Follow steps at

https://www.drupal.org/project/ngrok_drupal/issues/3151737

Edit services.yml

Then run with

ngrok http -host-header=rewrite lingod8.test:80

Running Tests

Locally

With the aliases defined before, you can just use something alike:

runtest '\Drupal\Tests\lingotek\Functional\Form\LingotekNodeBulkFormWithGroupModuleTest'

For speeding up the process, a useful trick is to replace “function test” with “function xxxtest” but the actual test method you want to run in the test class. Sadly you cannot specify just a test method with the run-tests.sh script anymore.

Running Javascript tests

Copy core/phpunit.xml.dist to core/phpunit.xml and configure it like:

  <php>
    <!-- Set error reporting to E_ALL. -->
    <ini name="error_reporting" value="32767"/>
    <!-- Do not limit the amount of memory tests take to run. -->
    <ini name="memory_limit" value="-1"/>
    <!-- Example SIMPLETEST_BASE_URL value: http://localhost -->
    <env name="SIMPLETEST_BASE_URL" value="http://lingod8.test"/>
    <!-- Example SIMPLETEST_DB value: mysql://username:password@localhost/databasename#table_prefix -->
    <env name="SIMPLETEST_DB" value="mysql://root:pwd@localhost/lingod8"/>
    <!-- Example BROWSERTEST_OUTPUT_DIRECTORY value: /path/to/webroot/sites/simpletest/browser_output -->
    <env name="BROWSERTEST_OUTPUT_DIRECTORY" value="/Users/penyaskito/Sites/lingod8/sites/default/simpletest"/>
    <!-- To disable deprecation testing completely uncomment the next line. -->
    <!-- <env name="SYMFONY_DEPRECATIONS_HELPER" value="disabled"/> -->
    <!-- Example for changing the driver class for mink tests MINK_DRIVER_CLASS value: 'Drupal\FunctionalJavascriptTests\DrupalSelenium2Driver' -->
    <env name="MINK_DRIVER_CLASS" value=''/>
    <!-- Example for changing the driver args to mink tests MINK_DRIVER_ARGS value: '["http://127.0.0.1:8510"]' -->
    <env name="MINK_DRIVER_ARGS" value=''/>
    <!-- Example for changing the driver args to phantomjs tests MINK_DRIVER_ARGS_PHANTOMJS value: '["http://127.0.0.1:8510"]' -->
    <env name="MINK_DRIVER_ARGS_PHANTOMJS" value=''/>
    <!-- Example for changing the driver args to webdriver tests MINK_DRIVER_ARGS_WEBDRIVER value: '["chrome", { "chromeOptions": { "w3c": false } }, "http://localhost:4444/wd/hub"]' For using the Firefox browser, replace "chrome" with "firefox" -->
    <env name="MINK_DRIVER_ARGS_WEBDRIVER" value='["chrome", { "chromeOptions": { "w3c": false } }, "http://lingod8.test:4444/wd/hub"]'/>
  </php>

You need to run in another shell:

chromedriver --port=4444 --whitelisted-ips='' --verbose --url-base=wd/hub

On Drupal.org

The full test suite is automatically run on a patch when the issue is set to Needs Review.

Tests can also be run manually by selecting Add test / Retest. This option will allow you to select various preconfigured test suites. This is usually useful if you suspect a different behavior between different core versions, or if there are some different code paths based on versions.

Custom suites can also be selected when testing is run manually. Customization options include the ability to choose the Drupal core, Lingotek module branch, and PHP/database versions.

Adding tests

TBD

Adding upgrade tests

TBD

Creating patches

TBD

If you upload a new patch, hide those uploaded from previous comments, so we only have the last WIP next to the summary.

We try to keep only the last relevant patch in the header, so when you visit an open issue you can easily see the relevant patch, and if it was already closed you only see the patch that was actually committed.

Creating only-test patches

If you are working on a bugfix instead of a new feature, it’s really useful to have side-by-side patches that succeed and fail, so we can ensure that there are tests for the actual bug.

By convention, this patches have the .only-test.patch extension. If you upload this before the actual patch with tests and fixes, the issue won’t turn to Needs Work automatically when it fails, reducing noise in the comments.

These patches are usually created by

git diff --cached tests/ > numberoftheissueondrupal.org-shortdescription-commentnumber.only-tests.patch

E.g.

git diff --cached tests/ > 3150292-document_update-callback-langcodes-2.only-tests.patch

Creating interdiffs

By convention, this patches have the .interdiff.previouscomment-newcomment.txt extension. When you upload this, unmark this one from the files section on drupal.org, so they are not listed on the header, but only in the comment itself.

We try to keep only the last relevant patch in the header, so when you visit an open issue you can easily see the relevant patch, and if it was already closed you only see the patch that was actually committed.

If you are working with the staging area, it’s easier to just add to the staging area everything that it’s already uploaded. Then, before creating a patch, do:

git diff > numberoftheissueondrupal.org-shortdescription.interdiff.lastcomment-ommentnumber.txt

E.g.

git diff > 3150292.document_update-callback-langcodes.interdiff.2-4.txt

Working with feature branches

TBD

Manual QA

Check you are in the right branch. The issue on Drupal.org should have the proper “Version” where the issue was fixed, and that should be a branch
1. If you are not, git branch -r will show all the remote branches and you can use git checkout -b <branch-name> origin/<branch-name>. E.g. git checkout -b 3.7.x origin/3.7.x
Pull the latest changes in the branch with git pull
Download the latest patch. E.g. wget https://drupal.org/issues/files/23124-my-issue-patch-123.patch
Apply the latest patch you just downloaded: git apply --index 23124-my-issue-patch-123.patch
QA

No matter if your QA passed or not successfully, you want to reset the changes applied from that patch for testing the next one. Use

git reset --hard HEAD

Commits

All commits happen by using the template provided by Drupal.org, which will be linking to the Drupal.org issue and crediting all the contributors that participated on that.

All patches need to have been code reviewed and approved, and the testbot must come back green (unless we are fixing a broken build, of course).

Giving credit

Take your time to go through the comments and patches and check the checkboxes for those that provided helpful comments (reporting the issue, posting patches or guiding them, reviewing or testing the patches). Feel free to uncheck those that don’t provide a positive direction or is just obvious that they are karma collectors.

Although, in general, be gentle and generous when providing credit.