Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
188 lines (133 loc) · 9.57 KB

CONTRIBUTING.md

File metadata and controls

188 lines (133 loc) · 9.57 KB
Raw

Contributing to mindee-api-php

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to mindee-api-php, which is hosted on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Code of Conduct

This project and everyone participating in it is governed by the following Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to contact@mindee.com.

How Can I Contribute

Reporting Bugs

Bugs are tracked as GitHub issues.

To help maintainers and the community to be efficient, follow these guidelines:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as many details as possible. When listing steps, don't just say what you did, but explain how you did it: which client and method you called, with which options, and what kind of file you sent (PDF, image, number of pages...).
  • Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Explain which behavior you expected to see instead and why.
  • If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.
  • Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

Include details about your configuration and environment:

  • Which version of mindee-api-php are you using? (composer show mindee/mindee)
  • Which PHP version, on which OS and architecture? (php -v, which also says whether PHP is thread-safe, ZTS, or not, NTS)
  • For PDF and image features: which version of the bernard-ledit extension? (php -r 'echo phpversion("bernard_ledit");')

If the problem is in the bernard-ledit extension itself, for example a crash, or a PDF or image it renders wrongly whatever the SDK does, report it on mindee/bernard-ledit instead.

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues.

Make sure to provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
  • Describe the current behavior and explain which behavior you expected to see instead and why.
  • Specify which version of mindee-api-php you're using, and your PHP version and OS.

Pull Requests

The process described here has several goals:

  • Maintain mindee SDK quality
  • Fix problems that are important to users
  • Engage the community in working toward the best possible SDK
  • Enable a sustainable system for mindee's maintainers to review contributions

Please follow these steps to have your contribution considered by the maintainers:

  1. Follow all instructions in the template
  2. Follow the styleguides
  3. Make sure the linters and the unit tests pass (see Development)

While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.

Development

Setup

You need PHP 8.1 or later, with the curl, fileinfo and json extensions, and Composer.

The test files live in a Git submodule, so clone with it:

git clone --recurse-submodules https://github.com/mindee/mindee-api-php.git
cd mindee-api-php
composer install

In an existing clone, run git submodule update --init --recursive instead.

composer install also sets up Git hooks through Whisky: composer lint runs before each commit, and composer test:unit before each push.

PDF and image features: the bernard-ledit extension

PDF and image operations (page cutting and merging, compression, crop and split extraction) rely on bernard-ledit, a native PHP extension. It is optional for users, but you need it to run the full unit test suite.

Refer to the version constraint in composer.json.

Install the pinned version with PIE:

composer setup:bernard-ledit                  # the version composer.json pins
composer setup:bernard-ledit -- 0.2.0         # another version, e.g. to try it before pinning it

This runs tools/install-bernard-ledit.sh, which installs the extension for the php on your PATH (set PHP to target another one), enables it, and checks that PHP loads the right version. PIE may ask for your password to write to PHP's extension directory. On Windows, run PIE directly with the pinned version, e.g. pie install mindee/bernard-ledit:0.1.0.

Check that it loaded:

php -r 'echo phpversion("bernard_ledit"), PHP_EOL;'

PHPStan reads the extension's classes from stubs/bernard_ledit.stubs.php, which matches the pinned version:

composer update:bernard-ledit-stubs           # stubs of the version composer.json pins
composer update:bernard-ledit-stubs v0.2.0    # stubs of another release

To move the SDK to a new bernard-ledit version:

  1. Change the version in the conflict line of composer.json.
  2. Run composer setup:bernard-ledit and composer update:bernard-ledit-stubs, then commit the updated stubs.
  3. Run the tests: CI installs the new version on its own.

Running the tests

Command What it runs
composer test:unit Unit tests (*Test.php); needs bernard-ledit
composer test:bernard-ledit-features Tests of the SDK's behavior when bernard-ledit is missing (tests/bernardleditfeatures.xml); run them without the extension
composer test:functional Tests against the Mindee API (*Functional.php); needs API keys, see below
composer test:smoke:v1, composer test:smoke:v2 The code samples
composer test:cli:v1, composer test:cli:v2 The command-line interface

Functional tests read their API keys and model IDs from environment variables, mainly MINDEE_API_KEY, MINDEE_V2_API_KEY and the MINDEE_V2_*_MODEL_ID variables. See .github/workflows/_test-integrations.yml for the full list.

A function deprecated in a recent PHP release only warns on that release, so also run the tests on the newest PHP version. CI runs the unit tests on every supported PHP version, on Linux, macOS and Windows. In tests/bernardleditfeatures.xml, PHP deprecations fail the tests (convertDeprecationsToExceptions).

Linting and formatting

composer lint      # PHPStan, php-cs-fixer and Rector, without changing any file
composer format    # applies php-cs-fixer's and Rector's fixes

Styleguides

Git Commit Messages

  • Start the message with the gitmoji that fits the change, followed by a short description in lowercase
  • 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 fewer
  • Reference issues and pull requests liberally after the first line

Examples:

  • 📝 add usage section in README
  • ✨ add support for split extraction
  • 🐛 fix page index out of range on multi-page crops

PHP Styleguide

We keep our code base consistent: PHP code follows the rules in .php-cs-fixer.dist.php, which build on PER Coding Style, the successor of PSR-12. PHPStan (phpstan.neon) and Rector (rector.php) also run on every commit. composer format fixes most style issues for you.