From cc2fa0d7775716b95f21235e8535fb6014b3e8df Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Mon, 26 Apr 2021 08:31:34 +0100 Subject: [PATCH] docs: move info to CONTRIBUTING, expand --- CONTRIBUTING.md | 221 ++++++++++++++++++++++++++++++++++++++++++------ README.md | 88 +------------------ 2 files changed, 198 insertions(+), 111 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea19841..51c4e49 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,41 +1,197 @@ -# **footnotes** Contributing Guide +# footnotes Contributing Guidelines -**footnotes** welcomes contributions! +This project welcomes contributions! + +This document describes everything you need to know about working with this +project. + +## Table of Contents + +* [Code of Conduct](#code-of-conduct) +* [Requesting Features and Reporting Bugs](#requesting-feature-and-reporting-bugs) +* [Development](#development) +* [Releases](#releases) +* [Translating](#translating) ## Code of Conduct Please read and ensure that you adhere to the project's [Code of Conduct][coc]. -## Requesting Features/Reporting Bugs +## Requesting Features and Reporting Bugs -To request a new feature or to report a bug, create an [Issue][new-issue] and -choose the correct template. +To request a new feature or to report a bug, create an [Issue][new-issue]: -## Contributing Code +* example templates are provided; +* if you are reporting a bug that has security implications, please see + the project [security guidelines][security]. -- **footnotes** uses [GitHub Flow][github-flow]; -- branch off of `main` to start developing (`git checkout -b `); -- ensure that your new branch has a descriptive name; -- create a remote copy of your new branch (`git push`); -- create a draft [pull request][pull-request] to merge your branch with `main` — - tag any related Issues, and if they are assigned to a Project board, this will - automatically move them into the ‘In Progress’ bucket; and -- when you think you're finished, un-draft your pull request — if the PR is - assigned to a Project board, this will automatically move it and any related - Issues into the ‘Review in progress’ bucket. +## Development -## Commits +### Version Control -- **footnotes** uses the [Conventional Commits][conventional-commits] for - commit message formatting; -- we recommend using [Commitizen][commitizen] to automate this: - - install it globally using `npm install -g commitizen`; - - use `git cz` instead of `git commit`. -- keep individual commits as small as possible. +Version control for this project uses [Git][git] for development and +[Apache Subversion][svn] for releases: -## Versioning +* The [development repository][dev-repo] is hosted on [GitHub][github]; and +* the [release repository][rel-repo] is hosted on the [WordPress Plugin Directory][wp-plugin-dir], +a Subversion repository hosted by the WordPress Plugins team: + * information on using the WordPress Plugin Directory can be found in the + [_WordPress Plugin Handbook_][wp-plugin-handbook]. -**footnotes** uses [WordPress Versioning][wpver]. +#### Branching + +This project uses the [GitHub Flow][github-flow] branching methodology: + +* branch off of `main` to start developing (`git checkout -b `); +* ensure that your new branch has a descriptive name (e.g., ‘fix-foo-bug’); +* create a remote copy of your new branch (`git push`); +* create a draft [pull request][new-pull-request] to merge your branch with `main`: + * tag any related or to-close Issues, Projects and Milestones: + * if any Issues are assigned to a Project board, this will automatically + move them into the ‘In Progress’ bucket. + * assign the PR to yourself unless you have a good reason not to. +* when you think you're finished, un-draft your pull request: + * if the request is assigned to a Project board, this will automatically + move it and any related Issues into the ‘Review in progress’ bucket. + +#### Committing + +This project uses the [Conventional Commits][conventional-commits] format for +commit messages: + +* commit message formatting can be automatically enforced by using + [Commitizen][commitizen]: + * install it globally using `npm install -g commitizen`; then + * use `git cz` instead of `git commit`. +* please keep individual commits as small and atomic as possible. + +### Configuration + +The only configurable environment variable is the `PRODUCTION_ENV` flag in +`src/footnotes.php`. This should always be set to `false` on this repo, and is +automatically flipped during the release process. + +### Code Formatting + +This repo. uses [Husky][husky] to run pre-commit code formatting and linting +on all staged files. This ensures that only style-conformant code can be +committed (although this can be bypassed by passing the `--no-verify` argument +to your `git commit` command). + +The individual commands used by Husky can also be called manually: + +* Run `composer run format` to run all format commands. +* Run `composer run format:fix` to attempt to automatically fix all formatter warnings + and errors. + +* Run `composer run lint` to run all linting commands. +* Run `composer run lint:fix` to attempt to automatically fix all linter warnings + and errors. + +_NB: `npm` can also be used in place of `composer`._ + +#### PHP + +PHP code must follow the [WordPress PHP Coding Standards][wpcs-php] and be +compatible with PHP 7.0+. + +1. Run `composer run lint:php` to lint all PHP files with + [PHP CodeSniffer][phpcs]; and +1. run `composer run lint:php:fix` to attempt to automatically fix warnings and + errors using the PHP Code Beautifier and Formatter tool. + +#### JavaScript + +JavaScript code must follow the [WordPress JavaScript Coding Standards][wpcs-js]. +JavaScript code targets the [ESNext][esnext] standard. + +1. Run `composer run format:js` to format all JS files with [Prettier] + [prettier]; and +1. run `composer run format:js:fix` to attempt to automatically fix warnings and + errors. + +1. Run `composer run lint:js` to lint all JS files with [ESLint][eslint]; and +1. run `composer run lint:js:fix` to attempt to automatically fix warnings and errors. + +Prettier and ESLint configuration settings are found in `package.json`. Prettier +ignore rules are found in `.prettierignore`. + +#### CSS + +CSS stylesheets must follow the [WordPress CSS Coding Standards][wpcs-css]. + +1. Run `composer run lint:css` to lint all CSS files with [stylelint] + [stylelint]; and +1. run `composer run lint:css:fix` to attempt to automatically fix warnings and + errors. + +stylelint configuration settings are found in `package.json`. + +#### Markdown + +* Run `composer run lint:md` to lint all Markdown files with [markdownLint] + [markdownlint]; and +* run `composer run lint:md:fix` to attempt to automatically fix warnings and errors. + +#### HTML + +Run `composer run lint:html` to lint all HTML files with [HTMLHint][htmlhint]. + +#### YAML + +Run `composer run validate:yaml` to validate all YAML files with [yaml-validator][yaml-validator]. + +#### JSON + +TODO + +### Testing + +TODO + +## Documentation + +This repo. uses [Husky][husky] to run pre-push documentation generation. This is +to guarantee that all HTML documentation on the remote repo. should be up-to-date, +but this step can be bypassed if necessary by passing the `--no-verify` flag to +the `git push` command. + +### Tooling + +HTML documentation of the codebase is generated using [phpDocumentor][phpdocumentor]. + +phpDocumentor configuration settings are found in `phpdoc.dist.xml`. + +### Documenting + +The codebase is documented using PHPDoc docblocks. + +### Documentation Commands + +| Command | Result | +|----------------|--------------------------------| +| `composer run docs` | Regenerate HTML documentation. | + +## Releases + +Only Project Collaborators can issue new releases. + +### Versioning + +This project uses [WordPress Versioning][wpver] for version numbering (as of 2.7). + +### Building + +Run `composer run build` to build the Plugin. + +### Releasing + +Run `composer run release` to run use the release handler: + +* this is still a WIP! +* TODO: move to a GitHub Action so that the only way of handling a release is to + create one on GitHub: + * TODO: create separate pre-release and non-pre-release Actions ## Translating @@ -43,8 +199,21 @@ Translations are welcome! [coc]: https://github.com/markcheret/footnotes/blob/main/CODE_OF_CONDUCT.md [new-issue]: https://github.com/markcheret/footnotes/issues/new/choose +[security]: https://github.com/markcheret/footnotes/blob/main/SECURITY.md +[git]: https://git-scm.com/ +[svn]: https://subversion.apache.org/ +[dev-repo]: https://github.com/markcheret/footnotes +[github]: https://github.com +[rel-repo]: https://plugins.svn.wordpress.org/footnotes/ +[wp-plugin-dir]: https://plugins.svn.wordpress.org/ +[wp-plugin-handbook]: https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/ [github-flow]: https://githubflow.github.io/ -[pull-request]: https://github.com/markcheret/footnotes/compare +[new-pull-request]: https://github.com/markcheret/footnotes/compare [conventional-commits]: https://www.conventionalcommits.org [commitizen]: https://www.npmjs.com/package/commitizen +[husky]: https://typicode.github.io/husky/#/ +[esnext]: https://esnext.github.io/esnext/ +[markdownlint]: https://github.com/DavidAnson/markdownlint +[htmlhint]: https://htmlhint.com/ +[yaml-validator]: https://www.npmjs.com/package/yaml-validator [wpver]: https://make.wordpress.org/core/handbook/about/release-cycle/version-numbering/ diff --git a/README.md b/README.md index 9a7db75..873c520 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,6 @@ Featured on [wpmudev][wpmudev] — cheers for the review, folks! * [Features](#features) * [Getting Started](#getting-started) -* [Deploying](#deploying) -* [Testing](#testing) -* [Code Formatting](#code-formatting) * [Documentation](#documentation) * [Acknowledgments](#acknowledgements) * [License](#license) @@ -38,9 +35,9 @@ Featured on [wpmudev][wpmudev] — cheers for the review, folks! This Plugin provides: -* fully customizable footnote start and end shortcodes; +* fully-customizable footnote start and end shortcodes; * stylable tooltips supporting hyperlinks and dedicated text; -* a responsive 'reference container', with customisable positioning; +* 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 @@ -57,92 +54,13 @@ This Plugin provides: * 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 - -This repo. uses pre-commit code formatting and linting on all staged files. -This ensures that only style-conformant code can be committed. - -The individual commands can also be called manually: - -* Run `composer run format` to run all format commands. -* Run `composer run format:fix` to attempt to automatically fix all formatter warnings - and errors. - -* Run `composer run lint` to run all linting commands. -* Run `composer run lint:fix` to attempt to automatically fix all linter warnings - and errors. - -### PHP Code - -PHP code must follow the [WordPress PHP Coding Standards][wpcs-php]. - -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 - -JavaScript code must follow the [WordPress JavaScript Coding Standards][wpcs-js]. - -* Run `composer run format:js` to format all JS files with [Prettier][prettier]. -* Run `composer run format:js:fix` to attempt to automatically fix warnings and errors. - -* Run `composer run lint:js` to lint all JS files with [ESLint][eslint]. -* Run `composer run lint:js:fix` to attempt to automatically fix warnings and errors. - -Prettier configuration settings are found in `.prettierrc`. - -ESLint configuration settings are found in `.eslintrc.js`. File ignore rules are -found in `.eslintignore`. - -### CSS Stylesheets - -JavaScript code must follow the [WordPress CSS Coding Standards][wpcs-css]. - -* Run `composer run lint:css` to format all CSS files with [stylelint][stylelint]. -* Run `npcomposerm run lint:css:fix` to attempt to automatically fix warnings and - errors. - -stylelint configuration settings are found in `.stylelint.json`. - ## Documentation -Run `composer run docs` to automatically generate HTML documentation with -[phpDocumentor][phpdocumentor]. - View the current docs [here][footnotes-docs]. ## Acknowledgements -Huge thanks to every **footnotes user**, contributor, bug reporter, feature +Huge thanks to every **footnotes** user, contributor, bug reporter, feature requester and fan! ## License