Skip to content

Latest commit

 

History

History
160 lines (116 loc) · 5.93 KB

CONTRIBUTING.md

File metadata and controls

160 lines (116 loc) · 5.93 KB

Contributing

Library Organization

The library's directory structure is set up to conform to the Standard PHP Skeleton specification, except for the app directory instead of src. That is due to Laravel's artisan make:* commands placing generated files in app and not being configurable.

The Composer script names are according to the Composer Script Names specification.

How the package works is explained below:

  • The Laravel services are bootstrapped in a minimal bootstrap/app.php.
  • Autodiscovered service providers are loaded into bootstrap/cache/packages.php and bootstrap/cache/services.php files by the post-autoload-dump hook defined in composer.json. The contents of bootstrap/cache are ignored by Git.
  • A minimal .env is necessary for running tests and migrations. This file is not ignored by Git, but included in the package. It does not contain any secrets.
  • A database/database.sqlite is created automatically after running composer install using the post-install-cmd hook defined in composer.json. It is referenced by the .env file, but ignored by Git. It is needed by some services like Cache to store the cache database table. That is why a migration for that table is included.
  • Tests are run using an in-memory SQLite database.

Prerequisites

To contribute to this project, you will need:

  • PHP 8.3+
  • Composer

For installing additional versions of PHP on the Ubuntu operating system, read How to run multiple PHP versions on Ubuntu on Digital Ocean's community portal. The article covers PHP 7.0 and 7.2 on Ubuntu 18.04, but it is also applicable to other PHP and Ubuntu versions.

Composer can just be installed with from the Ubuntu repositories. If the version in the Ubuntu repositories is too old, you can run:

composer self-update

Also consult Composer's documentation for more information.

Obtain Source Code

Clone the source code from GitHub:

git clone https://github.com/spoorsny/laravel-south-african-id

Install the Composer dependencies:

cd laravel-south-african-id
composer install

Code Style

The library follows the PSR 12 coding standard. To automatically update the source code to meet this standard, issue command:

composer cs-fix

Testing & Code Coverage

The library has tests located in the tests that are based on PHPUnit. To run the tests, from the root of the repository, issue command:

composer test

To also see what percentage of the source code gets executed when the tests are run, issue command:

composer test-coverage

Contributions are only accepted if they include tests (where necessary) and the code coverage is 100%.

The test data were generated using Faker with the en_ZA locale and the idNumber() method.

Branch Management

The Git branch that contains the canonical version of the library is named master. On GitHub, this branch is protected, meaning that commits cannot be added directly to the branch. Commits can only be added via a merged pull request.

To contribute to the source code, follow the fork & pull request workflow.

Pull requests are always merged by "Rebase and merge" or "Squash and merge". Merging is not possible if the branch of the pull request is not up-to-date with master. The purpose is to maintain a linear commit history that is easier to understand without merge commits.

If a pull request is meant to resolve a GitHub issue, add "Resolves #3" to the description of the pull request (replacing "3" with the relevant issue number). That way the issue is automatically closed when the pull request is merged.

Commit Message Convention

The commit messages of this library follows the Conventional Commit convention. Also see previous commits in the repository for how it is used. The idea is to simplify the creation and automation of changelogs.

At the moment, the library's Releases page on GitHub serves as the changelog, but automating the update of a CHANGELOG.md file is on the today list.

If a commit is related to a GitHub issue, add "Relates to #3" to the footer of the commit message (replacing "3" with the relevant issue number).

GitHub Actions Workflows

When a pull request is made, a Continuous Integration GitHub Actions workflow is automatically started, which:

  • lints the source code, fixing the code style and automatically creating a new commit
  • runs the tests
  • checks the code coverage to be 100%

All three jobs must be successful before the pull request can be merged. The workflow is run again on the master branch after the pull request is merged.

Publishing to Packagist & Semantic Versioning

The package has been registerd on Packagist under username @geoffreyvanwyk. Packagist automatically crawls the repository for updates and registers a new version based on tags.

This library follows Semantic Versioning. A new version of the package is indicated with a Git tag that starts with a v. A release is then also created on GitHub based on that tag, and GitHub's built-in release notes generator is used.