From ee7721da963d68290570acd5c5ce9c71901e5152 Mon Sep 17 00:00:00 2001 From: Hugo Sales Date: Thu, 16 Sep 2021 12:57:43 +0100 Subject: [PATCH] [DOCUMENTATION] Add documentation on developer tools --- bin/fix_license | 4 +- docs/developer/src/SUMMARY.md | 3 +- docs/developer/src/introduction.md | 11 +++-- docs/developer/src/tools.md | 71 ++++++++++++++++++++++++++++++ 4 files changed, 82 insertions(+), 7 deletions(-) create mode 100644 docs/developer/src/tools.md diff --git a/bin/fix_license b/bin/fix_license index e5f16ba4a0..fe5dd158a9 100755 --- a/bin/fix_license +++ b/bin/fix_license @@ -8,11 +8,9 @@ require INSTALLDIR . '/vendor/autoload.php'; use Functional as F; -use App\Util\Functional; - $filenames = glob(INSTALLDIR . '/src/*/*.php'); -$files = F\map($filenames, Functional::arity('file_get_contents', 1)); +$files = F\map($filenames, F\ary('file_get_contents', 1)); $old_licenses = ['/* {{{ License * This file is part of GNU social - https://www.gnu.org/software/social diff --git a/docs/developer/src/SUMMARY.md b/docs/developer/src/SUMMARY.md index 050520a078..c5aa997a73 100644 --- a/docs/developer/src/SUMMARY.md +++ b/docs/developer/src/SUMMARY.md @@ -3,6 +3,7 @@ - [Introduction](./introduction.md) - [Architecture](./architecture.md) - [Programming Style](./paradigms.md) +- [Tools](./tools.md) - [Exceptions](./exceptions.md) - [Events](./events.md) - [Database](./database.md) @@ -20,4 +21,4 @@ - [Initialization and Clean Up](./modules/lifetime.md) - [Debugging](./debugging.md) - [Low level](./core.md) - - [Overview](./core/overview.md) \ No newline at end of file + - [Overview](./core/overview.md) diff --git a/docs/developer/src/introduction.md b/docs/developer/src/introduction.md index 765ba63be2..336ad9cd95 100644 --- a/docs/developer/src/introduction.md +++ b/docs/developer/src/introduction.md @@ -9,9 +9,14 @@ of GNU social for those looking forward to making the most advanced contribution # What you need to dive in -At least a webserver such as [nginx](https://nginx.org/) and a DBMS such as [postgresql](https://www.postgresql.org/). + - A working [Docker](https://www.docker.com/) and [`docker-compose`](https://docs.docker.com/compose/) setup -Depending on what you want to do, you may want to setup a queues (and caching) system such as [redis](https://redis.io/). +This is the recommended setup, for simplicity and integration with the provided [tools](./tools.md). + +OR + + - At least a webserver such as [nginx](https://nginx.org/) and a DBMS such as [postgresql](https://www.postgresql.org/). + - Depending on what you want to do, you may want to setup a queues (and caching) system such as [redis](https://redis.io/). To learn how to set all of that up, you may refer to the [System Administrator's handbook](/administrator). @@ -29,4 +34,4 @@ The [Designer](/designer) one is an in-depth overview of the design motifs, and # Tests When what you're looking for (usage instructions of anything), refer to the `tests` directory. -The unit tests are properly commented and are very extensive, they try to cover every use scenario. \ No newline at end of file +The unit tests are properly commented and are very extensive, they try to cover every use scenario. diff --git a/docs/developer/src/tools.md b/docs/developer/src/tools.md new file mode 100644 index 0000000000..6011cc7421 --- /dev/null +++ b/docs/developer/src/tools.md @@ -0,0 +1,71 @@ +Tools +===== + +GNU social provides some tools to aid developers. Most of the more +common ones can be accessed with the `make` command, for the +corresponding `Makefile`. These tools range from giving you acess to a +shell in the PHP docker container, a repl in the application +environment, a PostgreSQL shell, running PHPStan, among others. + +Pre Commit Hooks +================ + +A `git` `pre-commit` hook is provided, which gets installed when +`composer install` is run. This hook is responsible for running +multiple things that aid in maintaing code quality. + +Specifically, we have setup: + - PHP Code Style fixer + - PHP Documenation Checker + - PHPStan + +These can be disabled for a given commit by prepending the command +with one of `SKIP_CS_FIX`, `SKIP_DOC_CHECK`, `SKIP_PHPSTAN` or +`SKIP_ALL`, to disable the corresponding step. + +### Example + + SKIP_PHPSTAN=1 git commit + +These should be used sparingly, but they're primarily useful for work +in process commits and when rebasing. + +Make +==== + +Check the `Makefile` for an up to date list of commands available, but +notable ones include: + - `php-shell` - A shell in the PHP docker container, where you can + run commands from the `bin` folder (see below) or `composer` + - `php-repl` - A REPL in the context of the application, allowing you + to run function for testing. Note that this requires explicitly + importing the needed classes with `use Class;` like in a regular file + - `psql-shell` - A PostgreSQL shell, if you need to edit the database + contents manually + - `database-force-schema-update` - If some entity changed, run this + to add/remove/update any missing fields + - `test` - Run PHPUnit tests + - `phpstan` - Run PHPStan + +These can be run by using `make php-repl`, or the desired command + +Bin +=== + +In addition, some useful scripts are provided in the `bin/` directory. +Typically, these should be run inside the Docker container. This can +be done by running `make php-shell` + +Specifically: + - `bin/console` - The Symfony console + - `bin/generate_entity_fields` - Update autogenerated entity code. + Must be run after changing database definitions, i.e. when altering + the `schemaDef` static method in a class that extends `Entity` + +Check the [Symfony Console +reference](https://symfony.com/doc/current/console.html) for details +on available commands. + +In addition to those, we have added `app:events`, which lists the +application events and their handlers and can be invoked as +`bin/console app:event`