mirror of
https://code.mensbeam.com/MensBeam/Arsse.git
synced 2024-12-22 21:22:40 +00:00
Documentation on repo structure
This commit is contained in:
parent
934c762cb8
commit
3ff93113fa
1 changed files with 48 additions and 6 deletions
54
README.md
54
README.md
|
@ -8,7 +8,53 @@ Information on how to install and use the software can be found in [the manual](
|
||||||
|
|
||||||
The main repository for The Arsse can be found at [code.mensbeam.com](https://code.mensbeam.com/MensBeam/arsse/), with a mirror also available [at GitHub](https://github.com/meansbeam/arsse/). The main repository is preferred, as the GitHub mirror can sometimes be out of date.
|
The main repository for The Arsse can be found at [code.mensbeam.com](https://code.mensbeam.com/MensBeam/arsse/), with a mirror also available [at GitHub](https://github.com/meansbeam/arsse/). The main repository is preferred, as the GitHub mirror can sometimes be out of date.
|
||||||
|
|
||||||
[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed.
|
[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install --no-dev` is recommended.
|
||||||
|
|
||||||
|
# Repository structure
|
||||||
|
|
||||||
|
## Library code
|
||||||
|
|
||||||
|
The code which runs The Arsse, contained in `/arsse.php`, is only a short stub: the application itself is composed of the classes found under `/lib/`, with the main ones being:
|
||||||
|
|
||||||
|
| Path | Description |
|
||||||
|
|----------------|---------------------------------------------------------|
|
||||||
|
| `CLI.php` | The command-line interface, including its documentation |
|
||||||
|
| `Conf.php` | Configuration handling |
|
||||||
|
| `Database.php` | High-level database interface |
|
||||||
|
| `Db/` | Low-level database abstraction layer |
|
||||||
|
| `REST/` | Protocol implementations |
|
||||||
|
| `REST.php` | General protocol handler for CORS, HTTP auth, etc. |
|
||||||
|
| `Arsse.php` | Singleton glueing the parts together |
|
||||||
|
|
||||||
|
The `/lib/Database.php` file is the heart of the application, performing queries on behalf of protocol implementations or the command-line interface.
|
||||||
|
|
||||||
|
Also necessary to the functioning of the application is the `/vendor/` directory, which contains PHP libraries which The Arsse depends upon. These are managed by Composer.
|
||||||
|
|
||||||
|
## Supporting data files
|
||||||
|
|
||||||
|
The `/locale/` and `/sql/` directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The `/www/` directory serves as a document root for a few static files to be made available to users by a Web server.
|
||||||
|
|
||||||
|
The `/dist/` directory, on the other hand, contains samples of configuration for Web servers and init systems. These are not used by The Arsse itself, but are merely distributed with it for reference.
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
The source text for The Arsse's manual can be found in `/docs/`, with pages written in [Markdown](https://spec.commonmark.org/current/) and converted to HTML [with Daux](#building-the-manual). If a static manual is generated its files will appear under `/manual/`.
|
||||||
|
|
||||||
|
In addition to the manual the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
The `/tests/` directory contains everything related to automated testing. It is itself organized as follows:
|
||||||
|
|
||||||
|
| Path | Description |
|
||||||
|
|--------------------|------------------------------------------------------------------------------------|
|
||||||
|
| `cases/` | The test cases themselves, organized in roughly the same structure as the code |
|
||||||
|
| `coverage/` | (optional) Generated code coverage reports |
|
||||||
|
| `docroot/` | Sample documents used in some tests, to be returned by the PHP's basic HTTP server |
|
||||||
|
| `lib/` | Supporting classes which do not contain test cases |
|
||||||
|
| `bootstrap.php` | Bootstrap script, equivalent to `/arsse.php`, but for tests |
|
||||||
|
| `phpunit.dist.xml` | PHPUnit configuration file |
|
||||||
|
| `server.php` | Simple driver for the PHP HTTP server used during testing |
|
||||||
|
|
||||||
# Common tasks
|
# Common tasks
|
||||||
|
|
||||||
|
@ -16,14 +62,10 @@ We use a tool called [Robo](https://robo.li/) to simplify the execution of commo
|
||||||
|
|
||||||
## Running tests
|
## Running tests
|
||||||
|
|
||||||
The Arsse has an extensive PHPUnit test suite; tests can be run by executing `./robo test`, which can be supplemented with any arguments understoof by PHPUnit. For example, to test only the Tiny Tiny RSS protocol, one could run `/robo test --testsuite TTRSS`.
|
The Arsse has an extensive [PHPUnit](https://phpunit.de/) test suite; tests can be run by executing `./robo test`, which can be supplemented with any arguments understoof by PHPUnit. For example, to test only the Tiny Tiny RSS protocol, one could run `/robo test --testsuite TTRSS`.
|
||||||
|
|
||||||
There is also a `test:quick` Robo task which excludes slower tests, and a `test:full` task which includes redundant tests in addition to the standard test suite
|
There is also a `test:quick` Robo task which excludes slower tests, and a `test:full` task which includes redundant tests in addition to the standard test suite
|
||||||
|
|
||||||
### Testing PostgreSQL and MySQL
|
|
||||||
|
|
||||||
TODO
|
|
||||||
|
|
||||||
### Test coverage
|
### Test coverage
|
||||||
|
|
||||||
Computing the coverage of tests can be done by running `./robo coverage`. Either [phpdbg](https://php.net/manual/en/book.phpdbg.php) or [Xdebug](https://xdebug.org) is required for this. An HTML-format coverage report will be written to `./tests/coverage/`.
|
Computing the coverage of tests can be done by running `./robo coverage`. Either [phpdbg](https://php.net/manual/en/book.phpdbg.php) or [Xdebug](https://xdebug.org) is required for this. An HTML-format coverage report will be written to `./tests/coverage/`.
|
||||||
|
|
Loading…
Reference in a new issue