Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
199 lines (145 loc) · 9.41 KB

CONTRIBUTING.md

File metadata and controls

199 lines (145 loc) · 9.41 KB
Raw

Contributing to Algolia for Magento 2

Contributions to the codebase are done using the fork & pull model. This contribution model has contributors maintaining their own copy of the forked codebase (which can easily be synced with the main copy). The forked repository is then used to submit a request to the base repository to “pull” a set of changes (hence the phrase “pull request”).

Contributions can take the form of new components/features, changes to existing features, tests, bug fixes, optimizations or just good suggestions.

The development team will review all issues and contributions submitted by the community. During the review we might require clarifications from the contributor.

Contribution requirements

  1. Contributions must pass Continous Integration checks.
  2. Pull requests (PRs) have to be accompanied by a meaningful description of their purpose. Comprehensive descriptions increase the chances of a pull request to be merged quickly and without additional clarification requests.
  3. Commits must be accompanied by meaningful commit messages.
  4. PRs which include bug fixing, must be accompanied with step-by-step description of how to reproduce the bug.
  5. PRs which include new logic or new features must be submitted along with:
  6. All automated tests are passed successfully:
    • CircleCI Magento 2.4 unit tests

Note: Automated PHPCS and PHP compatibility checks are planned to be re-enabled in CI. Until then, run them locally before submitting a PR. See Static analysis and Quality Tools.

Contribution process

If you are a new GitHub user, we recommend that you create your own free github account. By doing that, you will be able to collaborate with the Magento 2 development team, “fork” the Magento 2 project and be able to easily send “pull requests”.

  1. Fork the repository according to Fork instructions
  2. Create and test your work
    • Write tests
  3. Commit your work:
  4. When you are ready, send us a pull request
  5. Once your contribution is received, the development team will review the contribution and collaborate with you as needed to improve the quality of the contribution.

Continuous Integration checks

Automated continous integration checks are run on CircleCI.

Integration tests

Integration tests are run via PHPUnit and the extension follows Magento 2 framework to run integration tests.

Setup

  1. Copy test's database config to Magento integration tests directory 
    cp [[extension_root_dir]]/dev/tests/install-config-mysql.php [[magento_root_dir]]/dev/tests/integration/etc/install-config-mysql.php
  2. Fill the correct DB credentials to the newly created config file
  3. The tests use Algolia credentials from ENV variables:
    • ALGOLIA_APPLICATION_ID (mandatory)
    • ALGOLIA_SEARCH_API_KEY (mandatory)
    • ALGOLIA_API_KEY (mandatory)
    • INDEX_PREFIX (optional, defaults to "magento20tests_")
    • The variable can be set either:
      • Globally by exporting them ($ export ALGOLIA_APPLICATION_ID=FOO, repeat for each var)
      • Manually when running the tests ($ ALGOLIA_APPLICATION_ID=FOO ...other vars... testsRunningCommand)

Run

$ cd [[magento_root_dir]]/dev/tests/integration
$ ../../../vendor/bin/phpunit ../../../vendor/algolia/algoliasearch-magento-2/Test

Coding Style

To check the coding style the extension uses PHP-CS-Fixer.

The fixer follows Magento 2 default rules and extra rules defined by the extension's development team. The concrete rules can be found here:

  • Magento's default rules - can be found in the root directory of Magento 2 installation in .php-cs-fixer.dist.php file
  • Extension's rules

Definitions of each rule can be found in the documentation of PHP-CS-Fixer.

Run

Check:

$ cd [[magento_root_dir]]
$ php vendor/bin/php-cs-fixer fix vendor/algolia/algoliasearch-magento-2 --config=vendor/algolia/algoliasearch-magento-2/.php-cs-fixer.php -v --using-cache=no --allow-risky=yes --dry-run

Fix:

$ cd [[magento_root_dir]]
$ php vendor/bin/php-cs-fixer fix vendor/algolia/algoliasearch-magento-2 --config=vendor/algolia/algoliasearch-magento-2/.php-cs-fixer.php -v --using-cache=no --allow-risky=yes

Comments (not annotations)

Comments should be used only in rare cases where it really helps others (or your future self) to understand what the code does.

The code itself should be self descriptive. Each time you want to comment a code think first about rewriting the code to be more self explanatory. E. g. extract the piece of code to a better named class / method, which will describe what the code does.

Example of a bad comment:

/**
 * Method gets user ID
 */
public function getUserId() { ... }

Example of a good comment:

// In $potentiallyDeletedProductsIds there might be IDs of deleted products which will not be in a collection
if (is_array($potentiallyDeletedProductsIds)) {
    $potentiallyDeletedProductsIds = array_combine(
        $potentiallyDeletedProductsIds,
        $potentiallyDeletedProductsIds
    );
}

To learn more about good commenting you can read:

Static analysis

The extension uses the Magento2 coding standard provided by magento/magento-coding-standard - a set of PHP_CodeSniffer rules that enforce Magento 2 marketplace and coding requirements.

It automatically detects common issues including:

  • Raw SQL queries and SQL queries inside loops
  • Direct class instantiation (bypassing dependency injection)
  • Unnecessary collection loading
  • Excessive code complexity
  • Use of dangerous functions
  • Use of PHP superglobals

ERRORs block pull requests from being merged. WARNINGs should be avoided but do not block merges.

Setup

magento/magento-coding-standard is included as a dev dependency in standard Magento 2.4.x installations, so no additional setup is required if you are already running a Magento development environment.

To verify the standard is registered, run from your Magento root:

$ vendor/bin/phpcs -i

The output should include Magento2 in the list of installed standards.

If it is missing, install it:

$ composer require --dev magento/magento-coding-standard

Run

Run from your Magento root directory:

$ vendor/bin/phpcs --standard=Magento2 --extensions=php,phtml -n --error-severity=10 \
  --ignore-annotations \
  --ignore=*/dev/*,.circleci/* \
  vendor/algolia/algoliasearch-magento-2

To generate a JSON report:

$ vendor/bin/phpcs --standard=Magento2 --extensions=php,phtml -n --error-severity=10 \
  --ignore-annotations \
  --ignore=*/dev/*,.circleci/* \
  --report=json --report-file=report.json \
  vendor/algolia/algoliasearch-magento-2

Quality Tools

As an alternative to testing Code Styling and Static Analysis individually, you can use our Quality Tools tool that our CircleCI integration check against, to lint and test your changes.

You can install the tool via composer:

composer global require algolia/magento2-tools

Make sure to place Composer's system-wide vendor bin directory in your $PATH so the magento2-tool executable can be located by your system.

Finally, you can launch the quality tools with:

{command} path/to/magento/extension [vendor/bin/path/]

The second argument is optional. If omitted, the scripts will attempt to auto-resolve the vendor bin directory by checking for a local vendor/bin/ install (e.g. after running composer install in the package directory) and then falling back to the global Composer vendor bin. If neither is found, the tools are expected to be on your $PATH.

Here is the list of available commands:

  • magento2-lint: Runs the linter and fixes the found issues - configuration file under algoliasearch-magento-2/.php-cs-fixer.php.

  • magento2-analyse: Runs PHPStan static analysis. Uses phpstan.neon or phpstan.neon.dist from the extension directory if present; otherwise runs at level 1 with sensible defaults. Requires the extension to be installed within a Magento project (detects Magento root automatically).

  • magento2-php-compatibility: Checks if your code is compatible across all PHP versions supported by Magento.

  • magento2-test: Runs all previous commands in --dry-run / read-only mode (coding style, PHP compatibility, and PHPStan analysis).