From 7128ef42821e4e87b35fe8a804ce820787aa0581 Mon Sep 17 00:00:00 2001 From: Mark Cheret Date: Wed, 14 Apr 2021 23:36:21 +0200 Subject: [PATCH 1/9] Update php.yml #73 #70 --- .github/workflows/php.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml index 6dcf060..f20ca38 100644 --- a/.github/workflows/php.yml +++ b/.github/workflows/php.yml @@ -13,6 +13,9 @@ jobs: steps: - uses: actions/checkout@v2 + + - name: Update composer.lock + run: composer update - name: Validate composer.json and composer.lock run: composer validate --strict From 3d4286952cadced10178e9ddeb80825762b2d6e5 Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Wed, 14 Apr 2021 23:20:42 +0100 Subject: [PATCH 2/9] chore: update linting commands, correct license --- composer.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/composer.json b/composer.json index 4b3354c..6813f67 100644 --- a/composer.json +++ b/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", "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:fix": "./vendor/bin/phpcbf --standard='WordPress' --encoding=utf-8 -p --ignore=*/vendor/* ./*.php ./*/*.php ./*/*/*.php", - "lint-css": "echo TODO", - "lint-js": "echo TODO", + "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:css": "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" From 40d3d26d9ec786bea2931ead48a5e613eb0c4cc4 Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Wed, 14 Apr 2021 23:21:01 +0100 Subject: [PATCH 3/9] chore: re-write developer readme --- README.md | 162 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 112 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 99d11c2..fc87f7f 100644 --- a/README.md +++ b/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. 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 -1. Install [Composer](https://getcomposer.org/download/), if you don't have it already -1. Install dependencies (`composer install`) - - You will have to install `php-mbstring` manually if you do not already have it. +1. Read the [contributing guidelines][contributing]; +1. clone this repository (`git clone git@github.com:markcheret/footnotes.git`): + - we recommend that you use [VVV][vvv] for your local testing environment. +1. install [Composer][composer], if you don't have it already; and +1. install all dependencies (`composer install`): + - 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 -1. Run `composer run lint-php:fix` to attempt to automatically fix errors and warnings +This repo. uses pre-commit code formatting and linting on all staged files. +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. 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` - - The intention is to replace this with a proper parsing of the `.distignore` file +1. Run `composer run lint:php` to lint all JS/TS files with [PHP CodeSniffer][phpcs] +1. Run `composer run lint:php:fix` to attempt to automatically fix warnings and + errors with the PHP Code Beautifier and Formatter. + +### JavaScript Code -## 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; -- Styled tooltips supporting hyperlinks display **footnotes** or a dedicated text; -- 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. +Run `composer run docs` to automatically generate HTML documentation with +[phpDocumentor][phpdocumentor]. -## Example Usage - -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``with an awesome footnote`` -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/). +View the current docs [here][footnotes-docs]. ## 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 From e17167f7fea6683f0a59f1207cf6b2766efca2ae Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Wed, 14 Apr 2021 23:27:32 +0100 Subject: [PATCH 4/9] fix: add `--with-all-dependencies` flag --- .github/workflows/php.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml index f20ca38..c76b772 100644 --- a/.github/workflows/php.yml +++ b/.github/workflows/php.yml @@ -15,7 +15,7 @@ jobs: - uses: actions/checkout@v2 - name: Update composer.lock - run: composer update + run: composer update -W - name: Validate composer.json and composer.lock run: composer validate --strict From 7d6ae59b61421c15d1f6a94f634ad485b8d10437 Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Wed, 14 Apr 2021 23:34:09 +0100 Subject: [PATCH 5/9] fix: correct license --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index 6813f67..f817e43 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "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", + "license": "GPL-3.0-only", "scripts": { "release": "./_tools/release.sh", "release:commit": "composer run release -- -c", From 21bb9c0ba77531b4ccd267df29cb4ef33eec9228 Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Wed, 14 Apr 2021 23:34:20 +0100 Subject: [PATCH 6/9] chore: update lockfile --- composer.lock | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/composer.lock b/composer.lock index ddd8915..79b7024 100644 --- a/composer.lock +++ b/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", - "reference": "5b553c274b94af3f880cbaaf8fbab047f279a31c", + "url": "https://api.github.com/repos/laminas/laminas-code/zipball/e7e8f8a9c267520051d8026ff1da74823a3d8b97", + "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", From feb9995bc8ca025fb8ab323222cf2665d7d12659 Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Wed, 14 Apr 2021 23:35:13 +0100 Subject: [PATCH 7/9] test: comment out caching --- .github/workflows/php.yml | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml index c76b772..2cd4755 100644 --- a/.github/workflows/php.yml +++ b/.github/workflows/php.yml @@ -13,21 +13,18 @@ jobs: steps: - uses: actions/checkout@v2 - - - name: Update composer.lock - run: composer update -W - name: Validate composer.json and composer.lock run: composer validate --strict - - name: Cache Composer packages - id: composer-cache - uses: actions/cache@v2 - with: - path: vendor - key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }} - restore-keys: | - ${{ runner.os }}-php- + # - name: Cache Composer packages + #id: composer-cache + #uses: actions/cache@v2 + #with: + # path: vendor + # key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }} + # restore-keys: | + # ${{ runner.os }}-php- - name: Install dependencies run: composer install --prefer-dist --no-progress From 6891f58f2cc072734f41d074c766073b8c3c678d Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Wed, 14 Apr 2021 23:38:13 +0100 Subject: [PATCH 8/9] fix: ignore PHP version --- .github/workflows/php.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml index 2cd4755..f4ad093 100644 --- a/.github/workflows/php.yml +++ b/.github/workflows/php.yml @@ -27,7 +27,7 @@ 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" # Docs: https://getcomposer.org/doc/articles/scripts.md From 833097ea24657243e62224bf00b28692aeeac854 Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Wed, 14 Apr 2021 23:40:30 +0100 Subject: [PATCH 9/9] feat: re-add caching command, add linting command --- .github/workflows/php.yml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml index f4ad093..619c495 100644 --- a/.github/workflows/php.yml +++ b/.github/workflows/php.yml @@ -17,20 +17,21 @@ jobs: - name: Validate composer.json and composer.lock run: composer validate --strict - # - name: Cache Composer packages - #id: composer-cache - #uses: actions/cache@v2 - #with: - # path: vendor - # key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }} - # restore-keys: | - # ${{ runner.os }}-php- + - name: Cache Composer packages + id: composer-cache + uses: actions/cache@v2 + with: + path: vendor + key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }} + restore-keys: | + ${{ runner.os }}-php- - name: Install dependencies run: composer install --prefer-dist --no-progress --ignore-platform-reqs - # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit" - # Docs: https://getcomposer.org/doc/articles/scripts.md + - name: Lint PHP code + run: composer run lint:php + # TODO: Add tests # - name: Run test suite # run: composer run-script test