[DOCUMENTATION] Add documentation on developer tools

This commit is contained in:
Hugo Sales 2021-09-16 12:57:43 +01:00 committed by Diogo Peralta Cordeiro
parent b177cb69e7
commit ee7721da96
Signed by: diogo
GPG Key ID: 18D2D35001FBFAB0
4 changed files with 82 additions and 7 deletions

View File

@ -8,11 +8,9 @@ require INSTALLDIR . '/vendor/autoload.php';
use Functional as F; use Functional as F;
use App\Util\Functional;
$filenames = glob(INSTALLDIR . '/src/*/*.php'); $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 $old_licenses = ['/* {{{ License
* This file is part of GNU social - https://www.gnu.org/software/social * This file is part of GNU social - https://www.gnu.org/software/social

View File

@ -3,6 +3,7 @@
- [Introduction](./introduction.md) - [Introduction](./introduction.md)
- [Architecture](./architecture.md) - [Architecture](./architecture.md)
- [Programming Style](./paradigms.md) - [Programming Style](./paradigms.md)
- [Tools](./tools.md)
- [Exceptions](./exceptions.md) - [Exceptions](./exceptions.md)
- [Events](./events.md) - [Events](./events.md)
- [Database](./database.md) - [Database](./database.md)
@ -20,4 +21,4 @@
- [Initialization and Clean Up](./modules/lifetime.md) - [Initialization and Clean Up](./modules/lifetime.md)
- [Debugging](./debugging.md) - [Debugging](./debugging.md)
- [Low level](./core.md) - [Low level](./core.md)
- [Overview](./core/overview.md) - [Overview](./core/overview.md)

View File

@ -9,9 +9,14 @@ of GNU social for those looking forward to making the most advanced contribution
# What you need to dive in # 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). 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 # Tests
When what you're looking for (usage instructions of anything), refer to the `tests` directory. 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. The unit tests are properly commented and are very extensive, they try to cover every use scenario.

View File

@ -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`