Epic - Standardise repository in accordance with Big Bite’s recommended workflows

[jaymcp]

Brief

In an endeavour to ensure that all of our internal project repositories conform to the same standards and practices, I’m creating this ticket to track all of the changes required to be made to this repository. The Code Owner should use the information contained within this Epic to create individual tickets for each piece of work that needs doing.

Each repository will be assigned a Code Owner. This nominated person is often not the main contributor to the project, but is chosen from the pool of engineering strategy team members. The Code Ownership role is not intended to invalidate, or take credit for, the work of the project’s contributors; rather, they are there to make sure that the contributors’ efforts are not wasted. The Code Owner is responsible for task distribution and delegation—including issue management and code review—and are to assist the contributors with their efforts.

To that end, I will be creating a Pull Request to add a .github/CODEOWNERS file to the project, so that they are automatically assigned when a Pull Request is created. As a fallback, the Pull Request also names the @bigbite/lead-engineers GitHub user group, so that there is cover available, should the nominated owner be unavailable.

Tasks

Below is a list of tasks that need to be actioned in order to bring the repository into conformance with Big Bite’s current workflow and standards recommendations. In many cases, these will involve minimal changes. Some, however, may be more involved, or require someone with specific knowledge to action. For example, if the repository doesn’t use a recent version of Big Bite’s CircleCI workflow, advice from @markgoodyear may be necessary. The Code Owner should distribute tasks with that in mind.

Build Tools

All internal projects, where applicable, should be using Build Tools for its asset workflow.

• This repository uses a very old version of Build Tools, and should upgrade.

CircleCI

All internal projects, where applicable, should make use of CircleCI. Further, they should be using the Big Bite Orb ^v1.1.0.

• This repository should be using ^v1.1.0 of the Big Bite Orb as a minimum

PHPCS

All internal projects, where applicable, should be using Big Bite’s PHPCS config. This should be required as a developmental dependency via composer. The project’s [.]phpcs.xml[.dist] file should point directly the standard within the vendor directory, e.g. <rule ref="./vendor/bigbite/phpcs-config/BigBite" />.
Further, PHPCS should be run in the context of the project’s composer installation, e.g. ./vendor/bin/phpcs .. For ease, it is worth adding a composer script:

{
    "scripts": {
        "phpcs": "./vendor/bin/phpcs ."
    }
}

Lastly, CircleCI should be configured to run the project/phpcs build step.
More information on PHPCS can be found at https://bigbite.engineering/internal/documentation/tools/phpcs.

• This repository should be using Big Bite’s PHPCS config v2.0.0 (publicly available, no vcs entry required in composer.json)
• This repository’s [.]phpcs.xml[.dist] file should reference the Big Bite PHPCS standard from composer’s vendor directory
• This repository should configure CircleCI to run the project/phpcs build step

PHPStan

All internal projects, where applicable, should make use of PHPStan. PHPStan should be required as a developmental dependency via composer, and its phpstan.neon config file created in accordance with our base config in the Prefab Plugin Template repository: https://github.com/bigbite/prefab-plugin-template/blob/main/phpstan.neon.
Further, CircleCI should be configured to run the project/phpstan build step.
More information on PHPStan can be found at https://bigbite.engineering/internal/documentation/tools/phpstan.

• This repository should be using PHPStan
• This repository should use a phpstan.neon configuration like our Prefab Plugin Template
• This repository should configure CircleCI to run the project/phpstan build step

Dependabot

All internal projects should have Dependabot configured to scan for vulnerabilities.

Node Versioning

All internal projects, should they have npm dependencies, should include a .node-version file. This allows for fnm to automatically ensure that the user is on the correct Node version to work on the project, and alleviates cognitive overhead from debugging due to Node version mismatches.

• This repository should include a .node-version file

Readme

All internal projects are expected to have a good readme. A good readme should describe the purpose of the project, how to install and use said project, and how to contribute back to the project.

Documentation

We have a global documentation site — https://bigbite.engineering — within which resides documentation pulled from all repositories that have documentation written. Our goal is for all internal projects to provide documentation to this site, so that every project is documented in one place. It would be of great benefit for this repository to contribute to this documentation site. This repository can provide documentation by adding a docs/ directory into the project root directory, containing Markdown files, accompanied by a .bbdocs.yml file.

Branching Strategy

All internal projects, where applicable, should follow the branching strategy described in the RFC https://bigbite.engineering/rfcs/git-branching-model. Primary branches (main, staging/uat, develop) should have Branch Protection Rules enabled. The default branch should be develop, as that is the Pull Request target branch.

• This repository should follow Big Bite’s branching strategy
• This repository’s primary branches should have Branch Protection Rules enabled
• This repository’s default branch should be set to develop