Improve documentation. Add Contributing page.

albertoarena · Dec 21, 2024 · 8d10bd8 · 8d10bd8
1 parent 6523c16
commit 8d10bd8
Show file tree

Hide file tree

Showing 6 changed files with 224 additions and 102 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,99 @@
+# Contributing
+
+First off, thank you for considering contributing to Laravel Event Sourcing Generator! Your contributions are greatly
+appreciated and help make this project better for everyone.
+
+The following guidelines are here to ensure the contribution
+process runs smoothly.
+
+## How Can I Contribute?
+
+### 1. Reporting Bugs
+
+If you find a bug, please:
+
+- Check the [issue tracker](https://github.com/albertoarena/laravel-event-sourcing-generator/issues) to see if it has
+  already been reported.
+- Open a new issue if it hasn't been reported.
+    - Use a clear and descriptive title.
+    - Include steps to reproduce the issue, expected behavior, and actual behavior.
+    - Provide any relevant logs, screenshots, or code snippets.
+
+### 2. Suggesting Features
+
+We welcome feature requests! To suggest a feature:
+
+- Check the [issue tracker](https://github.com/albertoarena/laravel-event-sourcing-generator/issues) to see if the
+  feature has already been
+  suggested.
+- Open a new issue labeled `feature request`.
+    - Clearly explain the feature and why it would be beneficial.
+    - Include examples or use cases if possible.
+
+### 3. Submitting Code Changes
+
+Want to fix a bug or implement a feature? Great! Here’s how to contribute code:
+
+1. **Fork** the repository.
+2. Create a new **branch** for your work:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. **Make your changes** and ensure your code adheres to the project’s style guidelines.
+   ```bash
+   # Run Laravel Pint
+   composer fix
+   # Run LaraStan analysis
+   composer static
+   ```
+4. **Test your changes** to make sure everything works as expected.
+   ```bash
+   composer test
+   ```
+5. Refresh code coverage badge icon
+   ```bash
+   composer test-coverage
+   ```
+6. **Commit** your changes with a clear and concise commit message.
+7. **Push** your branch to your forked repository:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+8. Open a **pull request (PR)** to the main repository:
+    - Provide a detailed description of your changes.
+    - Reference any related issues.
+    - Wait for feedback or approval from the maintainers.
+
+### Improving Documentation
+
+If you find areas in the documentation that can be improved:
+
+- Open an issue to discuss your proposed changes.
+- Submit a pull request with your updates.
+
+## Etiquette
+
+To maintain a welcoming and collaborative environment:
+
+- **Be respectful:** Treat everyone with kindness and respect, even when there are disagreements.
+- **Be constructive:** Provide helpful, actionable feedback. Avoid harsh criticism.
+- **Be inclusive:** Encourage diverse perspectives and ensure your contributions are accessible to everyone.
+- **Be patient:** Remember that maintainers are volunteers and may not respond immediately. Allow time for reviews and
+  discussions.
+- **Acknowledge contributions:** Give credit to other contributors where applicable.
+
+## Code Guidelines
+
+- This project uses [Laravel Pint](https://laravel.com/docs/11.x/pint) and its code is analysed
+  using [LaraStan](https://github.com/larastan/larastan).
+- Write clear, maintainable, and well-documented code.
+- Ensure your code passes all tests and adheres to the project’s formatting rules.
+
+## Getting Help
+
+If you need help, feel free to:
+
+- Ask a question by opening an issue.
+- [Contact the main developer](https://github.com/albertoarena/)
+
+Thank you for contributing! Your support helps keep this project thriving.
diff --git a/README.md b/README.md
@@ -1,33 +1,27 @@
 # Laravel event sourcing generator
 
 ![build-test](coverage.svg)
-[![License](https://img.shields.io/badge/license-MIT-red.svg?style=flat-square)](LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-red.svg?style=flat-square)](LICENSE.md)
+![Version](https://img.shields.io/github/v/tag/albertoarena/laravel-event-sourcing-generator?label=version)
+![Code Size](https://img.shields.io/github/languages/code-size/albertoarena/laravel-event-sourcing-generator)
 
 Laravel event sourcing generator adds a new Artisan command that can generate a full domain directory structure
 for [Spatie event sourcing](https://github.com/spatie/laravel-event-sourcing).
 
 ## Table of Contents
 
+- [Changelog](#changelog)
+- [Contributing](#contributing)
 - [Installation](#installation)
     - [Compatibility](#compatibility)
     - [Install](#install)
 - [Usage](#usage)
     - [Show help](#show-help)
     - [Basic usage](#basic-usage)
-        - [Generate a model with same name of the domain](#generate-a-model-with-same-name-of-the-domain)
-        - [Generate a model with different domain](#generate-a-model-with-different-domain)
-        - [Generate a model with different domain and namespace](#generate-a-model-with-different-domain-and-namespace)
-        - [Generate a model from existing migration](#generate-a-model-from-existing-migration)
-        - [Generate a model from existing migration with PHPUnit tests](#generate-a-model-from-existing-migration-with-phpunit-tests)
-        - [Generate a model from existing migration with failed events and mail / Slack notifications](#generate-a-model-from-existing-migration-with-failed-events-and-mail--slack-notifications)
     - [Domain and namespace](#domain-and-namespace)
-        - [Directory structure](#directory-structure)
-        - [Specify the name of the domain](#specify-the-name-of-the-domain)
-        - [Specify the namespace](#specify-the-namespace)
     - [Advanced usage](#advanced-usage)
         - [Set primary key](#set-primary-key)
         - [Generate PHPUnit tests](#generate-phpunit-tests)
-    - [Advanced options](#advanced-options)
         - [Generate aggregates](#generate-aggregates)
         - [Generate reactors](#generate-reactors)
         - [Generate failed events](#generate-failed-events)
@@ -36,14 +30,26 @@ for [Spatie event sourcing](https://github.com/spatie/laravel-event-sourcing).
         - [Specify the path of root folder](#specify-the-path-of-root-folder)
 - [Limitations and future enhancements](#limitations-and-future-enhancements)
 
-## Installation
+## Changelog
 
 [⬆️ Go to TOC](#table-of-contents)
 
-## Compatibility
+Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
+
+## Contributing
+
+[⬆️ Go to TOC](#table-of-contents)
+
+Feel free to fork, improve and create a pull request.
+
+Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
+
+## Installation
 
 [⬆️ Go to TOC](#table-of-contents)
 
+### Compatibility
+
 | What                                                                        | Version         |
 |-----------------------------------------------------------------------------|-----------------|
 | PHP                                                                         | 8.2             |
@@ -54,8 +60,6 @@ for [Spatie event sourcing](https://github.com/spatie/laravel-event-sourcing).
 
 ### Install
 
-[⬆️ Go to TOC](#table-of-contents)
-
 ```shell
 composer require albertoarena/laravel-event-sourcing-generator
 ```
@@ -66,13 +70,13 @@ composer require albertoarena/laravel-event-sourcing-generator
 
 ```text
 php artisan make:event-sourcing-domain <model>
-  [--domain=<domain>]                            # The name of the domain
+  [-d|--domain=<domain>]                         # The name of the domain
   [--namespace=<namespace>]                      # The namespace or root folder (default: "Domain")
-  [--migration=<existing_migration_filename>]    # Indicate any existing migration for the model, with or without timestamp prefix
-  [--aggregate=<0|1>]                            # Indicate if aggregate must be created or not (accepts 0 or 1)
-  [--reactor=<0|1>]                              # Indicate if reactor must be created or not (accepts 0 or 1)
-  [--unit-test]                                  # Indicate if PHPUnit tests must be created
-  [--primary-key=<uuid|id>]                      # Indicate which is the primary key (uuid, id)
+  [-m|--migration=<existing_migration_filename>] # Indicate any existing migration for the model, with or without timestamp prefix
+  [-a|--aggregate=<0|1>]                         # Indicate if aggregate must be created or not (accepts 0 or 1)
+  [-r|--reactor=<0|1>]                           # Indicate if reactor must be created or not (accepts 0 or 1)
+  [-u|--unit-test]                               # Indicate if PHPUnit tests must be created
+  [-p|--primary-key=<uuid|id>]                   # Indicate which is the primary key (uuid, id)
   [--indentation=<indent>]                       # Indentation spaces
   [--failed-events=<0|1>]                        # Indicate if failed events must be created (accepts 0 or 1)
   [--notifications=<mail,no,slack,teams>]        # Indicate if notifications must be created, comma separated (accepts mail,no,slack,teams)
@@ -81,8 +85,6 @@ php artisan make:event-sourcing-domain <model>
 
 ### Show help
 
-[⬆️ Go to TOC](#table-of-contents)
-
 ```shell
 php artisan help make:event-sourcing-domain
 ```
@@ -95,17 +97,13 @@ php artisan help make:event-sourcing-domain
 
 #### Generate a model with same name of the domain
 
-[⬆️ Go to TOC](#table-of-contents)
-
 ```shell
 php artisan make:event-sourcing-domain Animal \
   --domain=Animal
 ```
 
 #### Generate a model with different domain
 
-[⬆️ Go to TOC](#table-of-contents)
-
 [Read documentation with examples](./docs/domain-and-namespace.md#choosing-the-name-of-the-domain)
 
 ```shell
@@ -115,8 +113,6 @@ php artisan make:event-sourcing-domain Tiger \
 
 #### Generate a model with different domain and namespace
 
-[⬆️ Go to TOC](#table-of-contents)
-
 [Read documentation with examples](./docs/domain-and-namespace.md#choosing-the-namespace)
 
 ```shell
@@ -127,8 +123,6 @@ php artisan make:event-sourcing-domain Tiger \
 
 #### Generate a model from existing migration
 
-[⬆️ Go to TOC](#table-of-contents)
-
 [Read documentation with examples](./docs/migrations.md)
 
 ```shell
@@ -139,8 +133,6 @@ php artisan make:event-sourcing-domain Animal \
 
 #### Generate a model from existing migration with PHPUnit tests
 
-[⬆️ Go to TOC](#table-of-contents)
-
 ```shell
 php artisan make:event-sourcing-domain Animal \
   --migration=create_animal_table \
@@ -149,8 +141,6 @@ php artisan make:event-sourcing-domain Animal \
 
 #### Generate a model from existing migration with failed events and mail / Slack notifications
 
-[⬆️ Go to TOC](#table-of-contents)
-
 ```shell
 php artisan make:event-sourcing-domain Animal \
   --migration=create_animal_table \
@@ -166,8 +156,6 @@ php artisan make:event-sourcing-domain Animal \
 
 #### Specify the name of the domain
 
-[⬆️ Go to TOC](#table-of-contents)
-
 [Read documentation with examples](./docs/domain-and-namespace.md#specify-the-name-of-the-domain)
 
 ```shell
@@ -177,8 +165,6 @@ php artisan make:event-sourcing-domain Animal --domain=Lion
 
 #### Specify the namespace
 
-[⬆️ Go to TOC](#table-of-contents)
-
 [Read documentation with examples](./docs/domain-and-namespace.md#specify-the-namespace)
 
 ```shell
@@ -191,7 +177,7 @@ php artisan make:event-sourcing-domain Tiger --namespace=MyDomain --domain=Anima
 
 #### Set primary key
 
-[⬆️ Go to TOC](#table-of-contents)
+[Read documentation with examples](./docs/advanced-usage.md#specify-primary-key)
 
 Default primary key is `uuid`. That will work with Aggregate class.
 
@@ -205,19 +191,15 @@ When importing migrations, primary key will be automatically loaded from file.
 
 #### Generate PHPUnit tests
 
-[⬆️ Go to TOC](#table-of-contents)
-
 [Read documentation with examples](./docs/unit-tests.md)
 
-### Advanced options
-
-[⬆️ Go to TOC](#table-of-contents)
+```shell
+php artisan make:event-sourcing-domain Animal --unit-test
+```
 
 #### Generate aggregates
 
-[⬆️ Go to TOC](#table-of-contents)
-
-[Read documentation with examples](./docs/advanced-options.md#generate-aggregates)
+[Read documentation with examples](./docs/advanced-usage.md#generate-aggregates)
 
 ```shell
 php artisan make:event-sourcing-domain Animal --aggregate=1
@@ -227,49 +209,39 @@ This is available only for models using `uuid` as primary key.
 
 #### Generate reactors
 
-[⬆️ Go to TOC](#table-of-contents)
-
-[Read documentation with examples](./docs/advanced-options.md#generate-reactors)
+[Read documentation with examples](./docs/advanced-usage.md#generate-reactors)
 
 ```shell
 php artisan make:event-sourcing-domain Animal --reactor=1
 ```
 
 #### Generate failed events
 
-[⬆️ Go to TOC](#table-of-contents)
-
-[Read documentation with examples](./docs/advanced-options.md#generate-failed-events)
+[Read documentation with examples](./docs/advanced-usage.md#generate-failed-events)
 
 ```shell
 php artisan make:event-sourcing-domain Animal --failed-events=1
 ```
 
 #### Generate notifications
 
-[⬆️ Go to TOC](#table-of-contents)
-
-[Read documentation with examples](./docs/advanced-options.md#generate-notifications)
+[Read documentation with examples](./docs/advanced-usage.md#generate-notifications)
 
 ```shell
 php artisan make:event-sourcing-domain Animal --notifications=<NOTIFICATIONS>
 ```
 
 #### Specify indentation
 
-[⬆️ Go to TOC](#table-of-contents)
-
-[Read documentation with examples](./docs/advanced-options.md#specify-the-indentation)
+[Read documentation with examples](./docs/advanced-usage.md#specify-the-indentation)
 
 ```shell
 php artisan make:event-sourcing-domain Animal --indentation=2
 ```
 
 #### Specify the path of root folder
 
-[⬆️ Go to TOC](#table-of-contents)
-
-[Read documentation with examples](./docs/advanced-options.md#specify-the-path-of-root-folder)
+[Read documentation with examples](./docs/advanced-usage.md#specify-the-path-of-root-folder)
 
 ```shell
 php artisan make:event-sourcing-domain Animal --root=src
@@ -281,19 +253,9 @@ php artisan make:event-sourcing-domain Animal --root=src
 
 ### Blueprint column types
 
-[⬆️ Go to TOC](#table-of-contents)
-
 [Read documentation](./docs/migrations.md#unsupported-column-types)
 
 ### Future enhancements
 
-[⬆️ Go to TOC](#table-of-contents)
-
 - support migrations that update table ([see documentation](./docs/migrations.md#update-migrations))
 - support PHP 8.3
-
-## Develop
-
-[⬆️ Go to TOC](#table-of-contents)
-
-Feel free to fork, improve and create a pull request!