From d06b35cfa4b23f5b89c722b249b07d6dd6e726d7 Mon Sep 17 00:00:00 2001 From: wodnikm-news Date: Wed, 6 Nov 2024 17:36:57 +0100 Subject: [PATCH] chore: Add backstage configuration and update relevant documentation. --- README.md | 71 ++++++++++++++++++++++++++++-------------- catalog-info.yaml | 19 +++++++++++ docs/CONTRIBUTING.md | 17 ++++++++++ docs/GETTINGSTARTED.md | 24 ++++++++++++++ docs/HELPWANTED.md | 3 ++ docs/extensibility.md | 22 +++++++++++++ 6 files changed, 132 insertions(+), 24 deletions(-) create mode 100644 catalog-info.yaml create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/GETTINGSTARTED.md create mode 100644 docs/HELPWANTED.md create mode 100644 docs/extensibility.md diff --git a/README.md b/README.md index 2d8abd4..749754c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,38 @@ -### NUK WP PHPCS config +# nuk-wp-phpcs-config This library contains WordPress VIP PHPCS configuration for NewsUK plugins and themes. -## Requirements -- PHP 8.2 -- WordPress 6.2 +## Architecture + +### Project Structure + +```text +- .circleci # CircleCI pipeline configuration files +- .github # GitHub configuration files +- NewsPress # NewsPress phpcs rulesets +- NewsUK # NewsUK phpcs rulesets +``` + +## Technical Documentation + +- [Package Extensibility](docs/extensibility.md) + +## Contribution + +More details on how to contribute to this package can be found in the [CONTRIBUTING.md](docs/CONTRIBUTING.md) file. + +### Minimal requirements + +- PHP 8.2 +- WordPress 6.2 + +## Development setup + +To build the package + +PHP setup + +- `composer install` ## Installation @@ -14,7 +42,10 @@ Composer install: composer require --dev newsuk/nuk-wp-phpcs-config ``` -## Using the ruleset +## Usage + +### Using the ruleset + Create a `phpcs.xml.dist` file in your project and add the following to use `NewsUK` ruleset: ```xml @@ -23,29 +54,21 @@ Create a `phpcs.xml.dist` file in your project and add the following to use `New ``` -💡 *It is recommended to use the `NewsUK` or `NewsPress` ruleset as it is without customising or overriding rules unless necessary.* -## Override or add custom rules -You can also override or add custom rules to the config as follows. +💡 *It is recommended to use the `NewsUK` or `NewsPress` ruleset as it is without customising or overriding rules unless necessary.* -```xml - - - - - - - - - - - - -``` -## Composer scripts +### Usage with Composer Add the following to `scripts` section in `composer.json` file to run linting. ```json "lint": "phpcs .", "lint:fix": "phpcbf .", -``` \ No newline at end of file +``` + +## Tagging and releasing + +The content schema uses Semantic Versioning `semver` for versioning. The package is released using [GitHub Releases](https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/about-releases). The release process is automated in Circle CI build step. To create a new release, follow these steps: + +- Update the relevant files with the new version. Commit the updated files. +- Push the changes to the master branch, by merging the associated pull request +- Create a release targeting the `master` branch within GitHub. diff --git a/catalog-info.yaml b/catalog-info.yaml new file mode 100644 index 0000000..cf9e945 --- /dev/null +++ b/catalog-info.yaml @@ -0,0 +1,19 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: nuk-wp-phpcs-config + description: PHPCS configuration for WordPress VIP plugins and themes. + tags: + - wordpress + - phpcs + - php + - lint + - coding-standards + - bu:newsuk + annotations: + circleci.com/project-slug: github/newsuk/nuk-wp-phpcs-config + jira/project-key: CPNT +spec: + type: library + lifecycle: development + owner: group:newsuk diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..3706f6e --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,17 @@ +# Contributing + +This package is maintained by the Times CMS team. + +## Code Contribution + +Developers from outside the team are encouraged to contribute back to this package as part of fix and feature requests. In doing so, developers should ensure their changes adhere to established naming conventions within the package. + +## Branching + +The `main` branch is the source of truth for the repo. Example: `feat/JIRA-ID-magic-wand` branch should be cut from `main` and used as the base for any development work. Feature and fix branches should be cut from the `main` branch, and follow the `feat/JIRA-ID-*`, `fix/JIRA-ID-*` naming convention. Pull requests for these branches should be targeted at the `main` branch. The branching strategy and the release process is documented [here](https://nidigitalsolutions.jira.com/wiki/spaces/NCP/pages/2329149445/Branching+and+Deployment). + +## Commit Messages + +Commit messages should follow the Conventional Commits spec, `type(issue-ref): description` + +For example, a feature update for issue CPNT-123 that adds a new text box might have a commit message like "feat(CPNT-123): add new text box" diff --git a/docs/GETTINGSTARTED.md b/docs/GETTINGSTARTED.md new file mode 100644 index 0000000..44c3296 --- /dev/null +++ b/docs/GETTINGSTARTED.md @@ -0,0 +1,24 @@ +# Getting Started + +This reference is intended for developers prior to starting work on this package. + +## Development Tools + +Developers should have the following installed at a minimum: + +- Git +- PHP +- Composer + +## Branching and Release + +Please review the documentation about tagging and release process be found in the [README](../README.md#tagging-and-releasing) prior to starting development. More details on branching can be found in [CONTRIBUTING](./CONTRIBUTING.md#branching). + +## File Structure + +Rulesets should be organized within "NewsPress" and "NewsUK" directories. + +## Additional Support + +Further questions can be directed to the Times CMS team in the [`#tm-timescms-team` Slack channel](https://newscorp.enterprise.slack.com/archives/C03JD1PU44B). + diff --git a/docs/HELPWANTED.md b/docs/HELPWANTED.md new file mode 100644 index 0000000..572f4ed --- /dev/null +++ b/docs/HELPWANTED.md @@ -0,0 +1,3 @@ +# Help Wanted + +This file should contain any TODO items for the project with which the Times CMS team would appreciate assistance. diff --git a/docs/extensibility.md b/docs/extensibility.md new file mode 100644 index 0000000..119f524 --- /dev/null +++ b/docs/extensibility.md @@ -0,0 +1,22 @@ +# Package Extensibility + +This package provides many ways for developers to customise the behaviour. + +## Ruleset overriding and adding custom rules + +You can also override or add custom rules to the config as follows. + +```xml + + + + + + + + + + + + +```