Skip to content

Contribute Code

Preparing the local environment

Start by setting up a web server, PHP and MySQL. We recommend Drupal VM for advanced users, Acquia Dev Desktop for beginners.

You will also need Git and Composer. Note that Drupal VM comes with Composer included.

Getting Commerce

The following command will download Drupal 8 + Commerce 2.x with all dependencies to the mystore folder:

composer create-project drupalcommerce/project-base mystore --prefer-source --stability dev

The –prefer-source option tells Composer to use Git clone as the download method.

When prompted, answer n to:

Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]?

This will keep the downloaded git repositories inside their parent folders (such as web/modules/contrib/commerce).

Tips:

  • The bin folder contains Drupal Console and PHPUnit.
  • The web folder represents the document root.
  • Composer commands are always run from the site root (mystore in this case).
  • Downloading additional modules: composer require "drupal/devel"
  • Updating an existing module: composer update drupal/address –with-dependencies

See the project-base README for more details.

Tip

Check out our Quick start documentation to get things running easily.

Preparing your fork

Note: You will need a GitHub account for contributing.

Visit the Commerce repository on GitHub and click the fork button. That will create a copy of the repository on your GitHub account.

Now go to the Commerce folder and add your fork:

cd /path/to/mystore
cd web/modules/contrib/commerce
git remote add fork git@github.com:YOUR_USER/commerce.git

Replace YOUR_USER with your username (the full url is shown on your fork’s GitHub page).

You will now be able to push new branches to your fork and create pull requests against the main repository.

Running tests

All of the Drupal Commerce tests are based on the PHPUnit framework. In order to run the tests you will need to copy the phpunit.xml.dist from the core directory and modify it for your environment. An in depth article on getting ready to run the tests can be found here: https://drupalcommerce.org/blog/45322/commerce-2x-unit-kernel-and-functional-tests-oh-my

cd /path/to/mystore/web
# Run PHPUnit tests
../bin/phpunit -c core/phpunit.xml modules/contrib/commerce

Example phpunit.xml environment settings.

This phpunit.xml assumes you will be using SQLite (requires PHP SQLite extension) and the Drupal site accessible at http://localhost:8080.

<!-- Snippet of environment settings. -->
  <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://localhost:8080"/>
    <!-- Example SIMPLETEST_DB value: mysql://username:password@localhost/databasename#table_prefix -->
    <env name="SIMPLETEST_DB" value="sqlite://localhost/sites/default/files/.ht.sqlite"/>
    <!-- Example BROWSERTEST_OUTPUT_DIRECTORY value: /path/to/webroot/sites/simpletest/browser_output -->
    <!--<env name="BROWSERTEST_OUTPUT_DIRECTORY" value="/path/to/drupal8/sites/simpletest/browser_output"/>-->
    <env name="BROWSERTEST_OUTPUT_DIRECTORY" value="/path/to/drupal8/sites/simpletest/browser_output"/>
    <ini name="display_errors" value="On" />
    <ini name="display_startup_errors" value="On" />
  </php>

You can run php -S localhost:8080 from within your Drupal site to allow the tests to run.

Choosing an issue

Commerce uses patches for contributing code changes and drupal.org for tracking issues. To choose an issue, go through the open issues, pick one you like and assign it to you.

If you need help choosing an issue or working on one, join the Commerce 2.x office hours. They are held every Wednesday at 5PM GMT+1 on the #commerce Drupal Slack channel.

Tip: You can also view the issue queue as a kanban board.

Creating a patch

Start by creating a branch for your work. The branch name should contain a brief summary of its id and the issue, e.g 2276369-fix-product-form-notice:

cd web/modules/contrib/commerce
git checkout -b 2276369-fix-product-form-notice

Once you’re done with writing your code and you've committed all changes to your branch, use diff to create a patch. For example, if the current version of Drupal Commerce is 8.x-2.x, create a patch like this:

git diff 8.x-2.x > fix-product-form-notice-2276369-13.patch

Name your patch with this pattern: [short-description]-[issue-number]-[comment-number].patch

Note that the [comment-number] should be the number of the comment you will post to the issue; if the issue currently has 22 comments, then your comment number will be 23. If you have just created a new issue, then the comment number for your patch will be 2.

Creating an interdiff

If your patch is not the initial patch for the issue, you should also create an interdiff. For an introduction to interdiffs and how to create them, see the Drupal.org documentation on Creating an interdiff. For example, you can use patchutils to create an interdiff for a new patch like this:

interdiff fix-product-form-notice-2276369-7.patch fix-product-form-notice-2276369-13.patch > interdiff-2276369-7-13.txt

The naming convention for interdiff files is: interdiff-[issue-number]-[comment-number-for-previous-patch]-[new-comment-number].txt

Using .txt as the extension ensures that the testbot will ignore your interdiff file.

Update the issue and its status

Now that you've created the patch and interdiff locally, create a new comment on the issue and add your files. Typically, your patch will get automatically queued for testing. If not, you can click the Add test / retest link that appears below your uploaded patch to trigger the testbot.

If there are any test failures, you should leave the issue status set to "Needs work" until the problems are resolved. If all tests pass, update the issue status to "Needs review" to get feedback from other members of the community and reviews by the module maintainers.

Do not set the status to "Fixed" even though you've provided a "fix" in the form of your patch. The Fixed status is used by the module maintainers to indicate that either the latest patch has been committed to the development repository or the question asked in the issue has been sufficiently answered in the comments.

Typically, an issue will need several cycles of reviews and revisions before it is ready to be committed to the Drupal Commerce project.

Patches

Reviewing patches created by other members of the community is another valuable way to contribute to Drupal Commerce.

Applying Patches

  • If you used composer create-project to create your site, you can use Composer to apply patches by modifying the composer.json file that's at the root of your project.

  • If you did not use composer create-project to create your site, you can use the Applying patches documentation provided by drupal.org to learn about patching options.

The following documentation describes the procedure for applying patches for a composer-managed site.

In the "extra" section of your composer.json file, you will see "installer-types" and "installer-paths". To add patches to your project, add a new "patches" group to "extra".

For example, your "extra" section looks something like this without any patches:

    "extra": {
        "installer-types": [
            "bower-asset",
            "npm-asset"
        ],
        "installer-paths": {
            "web/core": [
                "type:drupal-core"
            ],
            "web/libraries/{$name}": [
                "type:drupal-library",
                "type:bower-asset",
                "type:npm-asset"
            ],
            "web/modules/contrib/{$name}": [
                "type:drupal-module"
            ],
            "web/profiles/contrib/{$name}": [
                "type:drupal-profile"
            ],
            "web/themes/contrib/{$name}": [
                "type:drupal-theme"
            ],
            "drush/contrib/{$name}": [
                "type:drupal-drush"
            ]
        }
    }

Then suppose you want to apply a patch for a Drupal Commerce Issue: Issue #2901939: Move variations form to its own tab

  1. Copy the link address for the patch you want to apply. In this case, the link address for the patch is https://www.drupal.org/files/issues/2018-05-18/commerce-product-variations-tab-2901939-40.patch

  2. Make the following addition to the "extra" section of your composer.json file:

"patches": {
      "drupal/commerce": {
          "2901939: Move variations form to its own tab": "https://www.drupal.org/files/issues/2018-05-18/commerce-product-variations-tab-2901939-40.patch"
    }
}

Note that "drupal/commerce" is the project name. Then for that project, you provide the specific patch information. If you have multiple patches, the "extra" section of your composer.json file should look something like this:

    "extra": {
        "installer-types": [
            "bower-asset",
            "npm-asset"
        ],
        "installer-paths": {
            "web/core": [
                "type:drupal-core"
            ],
            "web/libraries/{$name}": [
                "type:drupal-library",
                "type:bower-asset",
                "type:npm-asset"
            ],
            "web/modules/contrib/{$name}": [
                "type:drupal-module"
            ],
            "web/profiles/contrib/{$name}": [
                "type:drupal-profile"
            ],
            "web/themes/contrib/{$name}": [
                "type:drupal-theme"
            ],
            "drush/contrib/{$name}": [
                "type:drupal-drush"
            ]
        },
        "patches": {
            "drupal/commerce": {
                "2901939: Move variations form to its own tab": "https://www.drupal.org/files/issues/2018-05-18/commerce-product-variations-tab-2901939-40.patch"
            },
            "drupal/core": {
                "2904908: Fetch User ID from route context views' contextual filter for any entity": "https://www.drupal.org/files/issues/fetch_user_id_from_route_for_all-2904908-13.patch"
            },
            "drupal/serial": {
                "2946075: Support migrating existing values": "https://www.drupal.org/files/issues/2946075-2.serial.Support-migrating-existing-values.patch"
            }
        }
    }

Once you've made the changes to composer.json, you can apply the patch by running:

composer update drupal/commerce

Reviewing patches

Once you've tested a patch, leave a comment on the issue. If the patch worked for you, you can change the issue status to "Reviewed & tested by the community". If the patch didn't work for you, you can change the issue status to "Needs work". Provide as many details as possible to help developers reproduce your results and figure out how to fix the patch.

How to get a Commerce issue committed

  • Up to date issue summary
  • Complete tests
    • If it is a bug report, tests are more important than the fix, they guarantee both that the bug exists and that the fix actually fixes it.
    • Make sure to have full test coverage, lazy test writing will stall your issue.
  • Reports of the patch working for others
    • Explain what you’re doing and what the patch fixes for you
    • This is helpful even if one person has already RTBC’d
  • Small single focus for each patch
    • Don’t try to fix 8 things at once. If needed, do the most common use case and can then cover additional use cases with additional patches.
    • A small patch means the reviewer can easily grasp the whole change quickly. Large and mixed patches require a lot more review and can’t be done quickly as the reviewer has to spend a lot of time understanding the whole patch. 4 little patches are faster than 1 big one.
  • Change Record entry
    • Write a change record entry if the patch requires ANY manual work from the site owner or changes existing functionality that might be breaking or confusing.

That’s it! Happy contributing!