From a8b3f6f8dccf8abcce7826b0813df3edd341f19c Mon Sep 17 00:00:00 2001 From: lotyp Date: Thu, 7 Mar 2024 16:24:57 +0200 Subject: [PATCH 1/2] docs: update readme, add contribution guide --- README.md | 82 ++++--------------------------------- docs/pages/_meta.json | 3 +- docs/pages/contributing.mdx | 58 ++++++++++++++++++++++++++ docs/theme.config.tsx | 10 ++--- 4 files changed, 71 insertions(+), 82 deletions(-) create mode 100644 docs/pages/contributing.mdx diff --git a/README.md b/README.md index 98bd5c79..77f55062 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@
- - +Logo for Light Mode +Logo for Dark Mode
@@ -17,7 +17,6 @@ Software License Commits since latest release Codecov -Scrutinizer build (GitHub/Bitbucket) @@ -34,84 +33,19 @@ # Laravel Cycle ORM Adapter -Package fully integrates [Cycle ORM](https://cycle-orm.dev) into [Laravel](https://laravel.com) framework. +Unlock the full potential of [Domain-Driven Design](https://en.wikipedia.org/wiki/Domain-driven_design) in your Laravel projects with the [wayofdev/laravel-cycle-orm-adapter](https://github.com/wayofdev/laravel-cycle-orm-adapter) โ€” the adapter package that seamlessly integrates the capabilities of [CycleORM](https://cycle-orm.dev) โ€” DataMapper ORM into [Laravel Framework](https://laravel.com). -* [Laravel Octane](https://laravel.com/docs/9.x/octane) ready! -* [Laravel Telescope](https://laravel.com/docs/9.x/telescope) compatible - -If you **like/use** this package, please consider **starring** it. Thanks! +This adapter bridges the gap between Laravel's rapid development capabilities and Cycle ORM's Data Mapper features, enabling you to craft complex, domain-centric applications, with separation of concerns, and a clear distinction between the domain model and the persistence layer.
-## ๐Ÿ’ฟ Installation - -### โ†’ Using Composer - -Require as dependency: - -```bash -$ composer req wayofdev/laravel-cycle-orm-adapter -``` - -
- -## ๐Ÿ’ป Usage - -### โ†’ Console Commands - -#### Migrations: - -| Command | Description | -| ------------------------ | ------------------------------------------------------------ | -| `cycle:migrate` | Perform one or all outstanding migrations.
`--one` Execute only one (first) migration. | -| `cycle:migrate:replay` | Replay (down, up) one or multiple migrations.
`--all` Replay all migrations. | -| `cycle:migrate:rollback` | Rollback one (default) or multiple migrations.
`--all` Rollback all executed migrations. | -| `cycle:migrate:init` | Init migrations component (create migrations table). | -| `cycle:migrate:status` | Get list of all available migrations and their statuses. | - -#### Database: - -| Command | Description | -| ------------------------ | ------------------------------------------------------------ | -| `cycle:db:list [db]` | Get list of available databases, their tables and records count.
`db` database name. | -| `cycle:db:table ` | Describe table schema of specific database.
`table` Table name (required).
`--database` Source database. | - -#### ORM and Schema: - -| Command | Description | -| ------------------- | ------------------------------------------------------------ | -| `cycle:orm` | Update (init) cycle schema from database and annotated classes. | -| `cycle:orm:migrate` | Generate ORM schema migrations.
`--run` Automatically run generated migration. | -| `cycle:orm:render` | Render available CycleORM schemas.
`--no-color` Display output without colors. | -| `cycle:orm:sync` | Sync Cycle ORM schema with database without intermediate migration (risk operation). | +If you **like/use** this package, please consider **starring** โญ๏ธ it. Thanks!
-## ๐Ÿงช Running Tests - -### โ†’ PHPUnit Tests - -To run tests, run the following command: - -```bash -$ make test -``` - -### โ†’ Static Analysis - -Code quality using PHPStan: - -```bash -$ make stan -``` - -### โ†’ Coding Standards Fixing - -Fix code using The PHP Coding Standards Fixer (PHP CS Fixer) to follow our standards: +## ๐Ÿ“š Documentation -```bash -$ make cs-fix -``` +The full documentation for the package is available at [https://laravel-cycle-orm-adapter.wayof.dev](https://laravel-cycle-orm-adapter.wayof.dev).
@@ -133,7 +67,7 @@ Created in **2022** by [lotyp / wayofdev](https://github.com/wayofdev) * The official [spiral/cycle-bridge](https://github.com/spiral/cycle-bridge) for Spiral Framework -* Alternative implementation of Cycle ORM for Laravel โ€” [wakebit/laravel-cycle](https://github.com/wakebit/laravel-cycle) +* Alternative implementation of Cycle ORM for Laravel โ€” [wakebit/laravel-cycle](https://github.com/wakebit/laravel-cycle) (abandoned)
diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index 055554f1..8bd4a5e1 100644 --- a/docs/pages/_meta.json +++ b/docs/pages/_meta.json @@ -3,5 +3,6 @@ "installation": "Installation", "configuration": "Configuration", "usage": "Usage", - "services": "Services" + "services": "Services", + "contributing": "Contributing" } diff --git a/docs/pages/contributing.mdx b/docs/pages/contributing.mdx new file mode 100644 index 00000000..e135c5ea --- /dev/null +++ b/docs/pages/contributing.mdx @@ -0,0 +1,58 @@ +import { Callout } from 'nextra-theme-docs' + +# Contributing + +If you would like to contribute to this project, please open an issue or a pull request. We are always looking for ways to improve the project and would love to hear your ideas. + +The latest changes are always in master branch, so please make your Pull Request against that branch. + +## ๐Ÿ’ป Workflow + + + Please feature/fix/update... into individual PRs (not one changing everything) + + +- Create a github fork. +- On your fork, create a branch, make the changes, commit and push. +- Create a pull-request to the master branch of this repository. + +## ๐Ÿงพ Checklist + +### โ†’ If Applicable + +- tests should be included as a part of your PR +- run `make hooks` to install the git hooks and pre-commit checks +- run `make test` or `make up && make ssh && vendor/bin/pest` to run them. +- `make lint` should be run to ensure the code is properly formatted and phpstan should be run to ensure the code is properly typed. +- documentation should be updated, please provide the corresponding documentation as well and make it part of the Pull Request + +## โœ‰๏ธ Git Message Format + +This repo adheres to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. +Commit messages are enforced through [commitizen](https://github.com/commitizen-tools/commitizen) and a [pre-commit](https://pre-commit.com), please use `make hooks` to install them. + +This leads to more readable messages that are easy to follow when looking through the project history and also allows to generate changelogs automatically. + +### โ†’ Allowed prefixes for commit messages + +- **feat** โ€” A new feature +- **fix** โ€” A bug fix +- **perf** โ€” A code change that improves performance +- **docs** โ€” Documentation only changes +- **style** โ€” Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons) +- **deps** โ€” Changes to the package.json or package-lock.json +- **refactor** โ€” A code change that neither fixes a bug nor adds a feature +- **ci** โ€” Changes to our CI configuration files and scripts +- **test** โ€” Adding missing tests or correcting existing tests +- **revert** โ€” Reverting a previous commit +- **build** โ€” Changes that affect the build system or external dependencies (example scopes: pnpm, renovate, github actions) +- **chore** โ€” Other changes that don't modify src or test files +- **security** โ€” A code change that fixes a security issue + +## ๐Ÿ”“ Security Vulnerabilities + +If you discover a security vulnerability within this package, please send an e-mail to WayOfDev via the@wayof.dev. All security vulnerabilities will be promptly addressed. + +## ๐Ÿค Code of Conduct + +We are using the [Contributor Covenant](https://www.contributor-covenant.org/) as our Code of Conduct, to keep discussion open and inclusive. Please, take a moment to read and follow our [Code of Conduct](https://github.com/wayofdev/laravel-cycle-orm-adapter/blob/master/.github/CODE_OF_CONDUCT.md). diff --git a/docs/theme.config.tsx b/docs/theme.config.tsx index b21fc113..5be839d1 100644 --- a/docs/theme.config.tsx +++ b/docs/theme.config.tsx @@ -1,9 +1,6 @@ -import React from 'react' import {DocsThemeConfig, useTheme} from 'nextra-theme-docs' - - const Logo = () => { - const {theme} = useTheme(); + const {resolvedTheme} = useTheme(); const title = 'Laravel CycleORM Adapter'; const lightLogo = ( @@ -27,7 +24,6 @@ const Logo = () => { ); - // Dark theme logo const darkLogo = ( { return (
- {theme === 'light' ? lightLogo : darkLogo} + {resolvedTheme === 'light' ? lightLogo : darkLogo} Laravel CycleORM Adapter + className="nx-ml-2 font-semibold whitespace-nowrap">{title}
); From 3b52afbfeab2574e30ebc9d4b5a7151a6d908a2c Mon Sep 17 00:00:00 2001 From: lotyp Date: Thu, 7 Mar 2024 16:31:23 +0200 Subject: [PATCH 2/2] docs: provide links in readme.md --- README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 77f55062..fd657345 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Software License Commits since latest release Codecov - +
@@ -25,8 +25,8 @@
- - +CycleORM + WayOfDev + Laravel Logo for Light GitHub Mode +CycleORM + WayOfDev + Laravel Logo for Dark GitHub Mode

@@ -49,6 +49,14 @@ The full documentation for the package is available at [https://laravel-cycle-or
+## ๐Ÿค Contributing + +Contributions are welcome! + +If you would like to contribute to the package, please see the [Contributing Guide](https://laravel-cycle-orm-adapter.wayof.dev/contributing) file for more information. + +
+ ## ๐Ÿค License [![Licence](https://img.shields.io/github/license/wayofdev/laravel-cycle-orm-adapter?style=for-the-badge&color=blue)](./LICENSE)