Merge pull request #84 from markcheret/fix-php-ci

fix: get PHP Composer GitHub Actions to pass

.github/workflows/php.yml

@@ -27,10 +27,11 @@ jobs:
           ${{ runner.os }}-php-
 
     - name: Install dependencies
-      run: composer install --prefer-dist --no-progress
+      run: composer install --prefer-dist --no-progress --ignore-platform-reqs
 
-    # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
+    - name: Lint PHP code
-    # Docs: https://getcomposer.org/doc/articles/scripts.md
+      run: composer run lint:php
 
+    # TODO: Add tests
     # - name: Run test suite
     #   run: composer run-script test

README.md

@@ -2,76 +2,138 @@
 
 # footnotes
 
-## Description
+Featured on [wpmudev][wpmudev] — cheers for the review, folks!
 
-Featured on [wpmudev](http://premium.wpmudev.org/blog/12-surprisingly-useful-wordpress-plugins-you-dont-know-about/) — cheers for the review, folks!
+**footnotes** aims to be the all-in-one solution for displaying an 
+automatically-generated list of references on your Page or Post. The Plugin 
+ships with a set of defaults while also empowering you to control how your 
+footnotes will be displayed.
 
-**footnotes** aims to be the all-in-one solution for displaying an automatically generated list of references on your Page or Post. The Plugin ships with a set of defaults while also empowering you to control how your footnotes are being displayed.
+**footnotes** gives you the ability to display well-formatted footnotes on your 
+WordPress Pages and Posts — those footnotes we know from offline publishing.
 
-**footnotes** gives you the ability to display well-formatted footnotes on your WordPress Pages and Posts — those footnotes we know from offline publishing.
+## Table of Contents
+
+* [Features](#features)
+* [Getting Started](#getting-started)
+* [Deploying](#deploying)
+* [Testing](#testing)
+* [Code Formatting](#code-formatting)
+* [Documentation](#documentation)
+* [Acknowledgments](#acknowledgements)
+* [License](#license)
+* [Contact Information](#contact-information)
+
+## Features
+
+This Plugin provides:
+
+- fully customizable footnote start and end shortcodes;
+- stylable tooltips supporting hyperlinks and dedicated text;
+- a responsive 'reference container', with customisable positioning;
+- a wide choice of different numbering styles;
+- a freely-configurable and optional backlink symbol;
+- footnote appearance customisation via dashboard settings and custom CSS style 
+  rules; and
+- editor buttons for easily adding shortcode tags.
 
 ## Getting Started
 
-1. Read the contributing guidelines
+1. Read the [contributing guidelines][contributing];
-1. Clone this repository (`git clone git@github.com:markcheret/footnotes.git`)
+1. clone this repository (`git clone git@github.com:markcheret/footnotes.git`):
-    - We recommend that you use [VVV](https://varyingvagrantvagrants.org/) for your local testing environment
+    - we recommend that you use [VVV][vvv] for your local testing environment.
-1. Install [Composer](https://getcomposer.org/download/), if you don't have it already
+1. install [Composer][composer], if you don't have it already; and
-1. Install dependencies (`composer install`)
+1. install all dependencies (`composer install`):
-    - You will have to install `php-mbstring` manually if you do not already have it.
+    - you will have to install `php-mbstring` manually if you do not already 
+      have it.
+     
+## Deploying
+
+Automated release deployments will be introduced soon.
+
+### Building
+
+1. Run `_tools/build-stylesheets.sh -c` to concatenate stylesheets;
+1. manually minify the output files in `css/tmp/`, saving them as `.min.css` files:
+    - the intention is to replace this with automated minification, meaning that
+    all of these steps can be rolled into a single `build` command.
+1. run `_tools/build-stylesheets.sh -d` to deploy the minified files to `dist/`:
+    - **this will delete any existing `dist/` folder!**
+1. run `composer run build` to move over the remaining files to `dist/`:
+    - currently, the files to include in a distribution are hard-coded in 
+      `_tools/build.sh`; but
+    - the intention is to replace this with a proper parsing of the `.distignore` 
+      file
+  
+### Releasing
+
+1. Ensure that you have configured your Git config. with SVN credentials;
+1. run the above [build](#building) commands; and
+1. run `composer run release` and follow the prompts.
+      
+## Testing
+
+Automated testing will be introduced soon.
 
 ## Code Formatting
 
-1. Run `composer run lint-php` to lint all PHP files
+This repo. uses pre-commit code formatting and linting on all staged files. 
-1. Run `composer run lint-php:fix` to attempt to automatically fix errors and warnings
+This ensures that only style-conformant code can be committed.
 
-## Releasing
+The individual commands used by the pre-commit hook can also be called manually:
 
-1. Run `composer run release`
+### PHP Code
 
-## Building
+PHP code must follow the [WordPress PHP Coding Standards][wpcs-php].
 
-1. Run `_tools/build-stylesheets.sh -c` to concatenate stylesheets
+1. Run `composer run lint:php` to lint all JS/TS files with [PHP CodeSniffer][phpcs]
-1. Manually minify the output files in `css/tmp/`, saving them as `.min.css` files
+1. Run `composer run lint:php:fix` to attempt to automatically fix warnings and 
-  - The intention is to replace this with automated minification, meaning that
+  errors with the PHP Code Beautifier and Formatter.
-    all of these steps can be rolled into a single `build` command.
+  
-1. Run `_tools/build-stylesheets.sh -d` to deploy the minified files to `dist/`
+### JavaScript Code
-  - **this will delete any existing `dist/` folder**
-1. Run `composer run build` to move over the remaining files to `dist/`
-  - Currently, the files to include in a distribution are hard-coded in `_tools/build.sh`
-  - The intention is to replace this with a proper parsing of the `.distignore` file
 
-## Updating Documentation
+JavaScript code must follow the [WordPress JavaScript Coding Standards][wpcs-js].
 
-1. Run `composer run docs`
+Automated linting and formatting will be introduced soon.
+  
+### CSS Stylesheets
 
-## Testing
+JavaScript code must follow the [WordPress CSS Coding Standards][wpcs-css].
 
-Unit tests are TODO.
+Automated linting and formatting will be introduced soon.
 
-## Main Features
+## Documentation
 
-- Fully customizable **footnotes** start and end shortcodes;
+Run `composer run docs` to automatically generate HTML documentation with 
-- Styled tooltips supporting hyperlinks display **footnotes** or a dedicated text;
+[phpDocumentor][phpdocumentor].
-- Responsive *Reference Container* at the end or positioned by shortcode;
-- Display the **footnotes** *Reference Container* inside a Widget;
-- Wide choice of numbering styles;
-- Freely configurable and optional backlink symbol;
-- Configure the **footnotes'** appearance by dashboard settings and Custom CSS style rules;
-- Button in both the Visual and the Text editor to add shortcodes around selection.
 
-## Example Usage
+View the current docs [here][footnotes-docs].
-
-These are a few examples of possible ways to delimit footnotes:
-
-1. Your awesome text`((`with an awesome footnote`))`
-2. Your awesome text`[ref]`with an awesome footnote`[/ref]`
-3. Your awesome text`<fn>`with an awesome footnote`</fn>`
-4. Your awesome text`custom-shortcode`with an awesome footnote`custom-shortcode`
-
-## Where to get footnotes?
-
-The current version is available on the [WordPress.org Plugin Directory](https://wordpress.org/plugins/footnotes/).
 
 ## Acknowledgements
 
-Huge thanks to every **footnotes user**, contributor, bug reporter, feature requester and fan!
+Huge thanks to every **footnotes user**, contributor, bug reporter, feature 
+requester and fan!
+
+## License
+
+This project is licensed under the [GNU GPL v3][gpl-v3].
+
+## Contact Information 
+
+| Name          | Link(s)               |
+|---------------|-----------------------|
+|Mark Cheret		| [Email][mcheret] 			|
+
+[wpmudev]: http://premium.wpmudev.org/blog/12-surprisingly-useful-wordpress-plugins-you-dont-know-about/
+[php]: https://www.php.net/
+[contributing]: https://github.com/markcheret/footnotes/blob/main/CONTRIBUTING.md
+[vvv]: https://varyingvagrantvagrants.org/
+[composer]: https://getcomposer.org/download/
+[wpcs-php]: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/
+[phpcs]: https://github.com/squizlabs/PHP_CodeSniffer
+[wpcs-js]: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/
+[wpcs-css]: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/
+[phpdocumentor]: https://phpdoc.org/
+[footnotes-docs]: https://markcheret.github.io/footnotes/
+[gpl-v3]: https://www.gnu.org/licenses/gpl-3.0.en.html
+[mcheret]: mailto:mark@cheret.de

composer.json

@@ -1,15 +1,15 @@
 {
     "name": "markcheret/footnotes",
     "description": "footnotes aims to be the all-in-one solution for displaying an automatically-generated list of references on your WordPress Page or Post.",
-    "license": "GPL-3.0-or-later",
+    "license": "GPL-3.0-only",
     "scripts": {
         "release": "./_tools/release.sh",
         "release:commit": "composer run release -- -c",
         "build": "./_tools/build.sh",
-        "lint-php": "./vendor/bin/phpcs --standard='WordPress' --colors --encoding=utf-8 -n -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php",
+        "lint:php": "./vendor/bin/phpcs --standard='WordPress' --colors --encoding=utf-8 -n -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php",
-        "lint-php:fix": "./vendor/bin/phpcbf --standard='WordPress' --encoding=utf-8 -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php", 
+        "lint:php:fix": "./vendor/bin/phpcbf --standard='WordPress' --encoding=utf-8 -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php", 
-        "lint-css": "echo TODO",
+        "lint:css": "echo TODO",
-        "lint-js": "echo TODO",
+        "lint:js": "echo TODO",
         "docs": "./vendor/bin/phpdoc -d . -t ./docs --ignore vendor/",
         "commit": "./vendor/bin/php-commitizen commit -- ./.php-commitizen.php",
         "post-install-cmd": "./_tools/setup.sh"

composer.lock

@@ -482,16 +482,16 @@
         },
         {
             "name": "laminas/laminas-code",
-            "version": "4.1.0",
+            "version": "4.2.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/laminas/laminas-code.git",
-                "reference": "5b553c274b94af3f880cbaaf8fbab047f279a31c"
+                "reference": "e7e8f8a9c267520051d8026ff1da74823a3d8b97"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/laminas/laminas-code/zipball/5b553c274b94af3f880cbaaf8fbab047f279a31c",
+                "url": "https://api.github.com/repos/laminas/laminas-code/zipball/e7e8f8a9c267520051d8026ff1da74823a3d8b97",
-                "reference": "5b553c274b94af3f880cbaaf8fbab047f279a31c",
+                "reference": "e7e8f8a9c267520051d8026ff1da74823a3d8b97",
                 "shasum": ""
             },
             "require": {
@@ -549,7 +549,7 @@
                     "type": "community_bridge"
                 }
             ],
-            "time": "2021-03-27T13:55:31+00:00"
+            "time": "2021-04-14T22:05:06+00:00"
         },
         {
             "name": "laminas/laminas-eventmanager",