From bd91beec74a8c03b536b037005badf75e132b276 Mon Sep 17 00:00:00 2001 From: Luiz Marin <67489841+luizcmarin@users.noreply.github.com> Date: Fri, 19 Apr 2024 10:09:16 -0300 Subject: [PATCH] Docs folder standardization and other fixes --- LICENSE.md | 8 ++--- README.md | 25 ++++++++++---- docs/guide/en/testing.md | 69 +++++++++++++++++++++++++++++++++++++ docs/guide/pt-BR/testing.md | 44 +++++++++++++++++++++++ docs/internals.md | 5 ++- 5 files changed, 138 insertions(+), 13 deletions(-) create mode 100644 docs/guide/en/testing.md create mode 100644 docs/guide/pt-BR/testing.md diff --git a/LICENSE.md b/LICENSE.md index bc5674fe..6a920d60 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,17 +1,17 @@ -Copyright © 2008 by Yii Software (https://www.yiiframework.com/) +Copyright © 2008 by Yii Software () All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright +* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright +* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - * Neither the name of Yii Software nor the names of its +* Neither the name of Yii Software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. diff --git a/README.md b/README.md index 58e624f1..6a255f55 100644 --- a/README.md +++ b/README.md @@ -41,15 +41,28 @@ The package could be installed via composer: composer require yiisoft/db-oracle ``` -## Usage +## Documentation -For config connection to Oracle database check [Connecting Oracle](https://github.com/yiisoft/db/blob/master/docs/en/connection/oracle.md). +English: -[Check the documentation docs](https://github.com/yiisoft/db/blob/master/docs/en/README.md) to learn about usage. +- For config connection to Mysql, MariaDb database check [Connecting MySQL/MariaDb](https://github.com/yiisoft/db/blob/master/docs/en/connection/oracle.md) +- [Check the documentation](https://github.com/yiisoft/db/blob/master/docs/en/README.md) to learn about usage -## Testing +Portuguese - Brazil: -[Check the documentation](/docs/en/testing.md) to learn about testing. +- For config connection to Mysql, MariaDb database check [Connecting MySQL/MariaDb](https://github.com/yiisoft/db/blob/master/docs/pt-BR/connection/mysql.md) +- [Check the documentation](https://github.com/yiisoft/db/blob/master/docs/pt-BR/README.md) to learn about usage + +Testing: + +- [English](docs/guide/en/testing.md) +- [Portuguese - Brazil](docs/guide/pt-BR/testing.md) +- More information can be found in the [Internals.](docs/internals.md) + +## Support + +If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that. +You may also check out other [Yii Community Resources](https://www.yiiframework.com/community). ## Support the project @@ -65,7 +78,7 @@ For config connection to Oracle database check [Connecting Oracle](https://githu ## License -The Yii Framework Oracle Extension is free software. It is released under the terms of the BSD License. +The Yii Access is free software. It is released under the terms of the BSD License. Please see [`LICENSE`](./LICENSE.md) for more information. Maintained by [Yii Software](https://www.yiiframework.com/). diff --git a/docs/guide/en/testing.md b/docs/guide/en/testing.md new file mode 100644 index 00000000..5304f403 --- /dev/null +++ b/docs/guide/en/testing.md @@ -0,0 +1,69 @@ +# Testing + +## Github actions + +All our packages have github actions by default, so you can test your [contribution](https://github.com/yiisoft/db-oracle/blob/master/.github/CONTRIBUTING.md) in the cloud. + +> Note: We recommend pull requesting in draft mode until all tests pass. + +## Docker image + +For greater ease it is recommended to use docker containers, for this you can use the [docker-compose.yml](https://docs.docker.com/compose/compose-file/) file that is in the docs folder. + +1. [Oracle 21](/docker-compose.yml) + +For running the docker containers you can use the following command: + +```shell +docker compose up -d +``` + +## Unit testing + +The package is tested with [PHPUnit](https://phpunit.de/). + +The following steps are required to run the tests: + +1. Run the docker container for the dbms. +2. Install the dependencies of the project with composer. +3. Run the tests. + +```shell +vendor/bin/phpunit +``` + +### Mutation testing + +The package tests are checked with [Infection](https://infection.github.io/) mutation framework with +[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it: + +```shell +./vendor/bin/roave-infection-static-analysis-plugin +``` + +## Static analysis + +The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis: + +```shell +./vendor/bin/psalm +``` + +## Rector + +Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or +use either newest or any specific version of PHP: + +```shell +./vendor/bin/rector +``` + +## Composer require checker + +This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if all dependencies are correctly defined in `composer.json`. + +To run the checker, execute the following command: + +```shell +./vendor/bin/composer-require-checker +``` diff --git a/docs/guide/pt-BR/testing.md b/docs/guide/pt-BR/testing.md new file mode 100644 index 00000000..5475ee5d --- /dev/null +++ b/docs/guide/pt-BR/testing.md @@ -0,0 +1,44 @@ +# Testing + +## Github actions + +All our packages have github actions by default, so you can test your [contribution](https://github.com/yiisoft/db-mysql/blob/master/.github/CONTRIBUTING.md) in the cloud. + +> Note: We recommend pull requesting in draft mode until all tests pass. + +## Docker image + +For greater ease it is recommended to use docker containers, for this you can use the [docker-compose.yml](https://docs.docker.com/compose/compose-file/) file that is in the docs folder. + +1. [MySQL 8](../../../docker-compose.yml) +2. [MariaDB 10.11](../../../docker-compose-mariadb.yml) + +For running the docker containers you can use the following command: + +MySQL 8.0. + +```dockerfile +docker compose up -d +``` + +MariaDB 10.11. + +```dockerfile +docker compose -f docker-compose-mariadb.yml up -d +``` + +## Unit testing + +The package is tested with [PHPUnit](https://phpunit.de/). + +The following steps are required to run the tests: + +1. Run the docker container for the dbms. +2. Install the dependencies of the project with composer. +3. Run the tests. + +```shell +vendor/bin/phpunit +``` + +- More information can be found in the [Internals.](../../internals.md) diff --git a/docs/internals.md b/docs/internals.md index 02f5bc6e..7b62d12d 100644 --- a/docs/internals.md +++ b/docs/internals.md @@ -58,10 +58,9 @@ use either newest or any specific version of PHP: ./vendor/bin/rector ``` -## Dependencies +## Composer require checker -Use [ComposerRequireChecker](https://github.com/maglnet/ComposerRequireChecker) to detect transitive -[Composer](https://getcomposer.org/) dependencies. +This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if all dependencies are correctly defined in `composer.json`. To run the checker, execute the following command: