fix(doc) : grammatical and contextual issues

Contributing.md

@@ -1,15 +1,14 @@
-### Contributing Guidelines for Hashicorp Boundary and Vault Stack
+# Contributing Guidelines for HashiCorp Boundary and Vault Stack
 
-Thank you for considering contributing to the Hashicorp Boundary and Vault Stack project! Contributions help improve the project and are highly appreciated. To ensure smooth collaboration, please follow the guidelines below.
+Thank you for considering contributing to the HashiCorp Boundary and Vault Stack project! Your contributions are invaluable to the project's improvement. To ensure smooth collaboration, please follow the guidelines outlined below.
 
 ## Table of Contents
 - [Getting Started](#getting-started)
 - [Types of Contributions](#types-of-contributions)
   - [Reporting Issues](#reporting-issues)
+  - [Commit Messages](#commit-messages)
   - [Submitting Pull Requests](#submitting-pull-requests)
   - [Code Style and Best Practices](#code-style-and-best-practices)
-  - [Commit Messages](#commit-messages)
-  - [Testing](#testing)
 - [Guidelines for Specific Tasks](#guidelines-for-specific-tasks)
   - [Terraform](#terraform)
   - [Ansible](#ansible)
@@ -20,100 +19,94 @@ Thank you for considering contributing to the Hashicorp Boundary and Vault Stack
 
 ## Getting Started
 
-1. **Fork the repository**: Start by forking the repository to your GitHub account.
+1. **Fork the Repository**: Begin by forking the repository to your GitHub account.
 
-2. **Clone the repository**: Clone your forked repository to your local machine:
+2. **Clone the Repository**: Clone your forked repository to your local machine:
     ```bash
     git clone https://github.com/your-username/boundary-vault-stack.git
     cd boundary-vault-stack
     ```
 
-3. **Set up your environment**: Ensure you have the necessary dependencies installed as outlined in the [documentation](./artifacts/wiki.md).
+3. **Set Up Your Environment**: Ensure you have the necessary dependencies installed as outlined in the [documentation](./artifacts/wiki.md).
 
-4. **Read the documentation**: Familiarize yourself with the project by thoroughly reading the [documentation](./artifacts/wiki.md) and reviewing the [diagram of the automation workflow](https://linktw.in/PloXtt).
+4. **Review the Documentation**: Familiarize yourself with the project by thoroughly reading the [documentation](./artifacts/wiki.md) and reviewing the [automation workflow diagram](https://linktw.in/PloXtt).
 
 ## Types of Contributions
 
 ### Reporting Issues
 
 If you encounter any bugs, errors, or have suggestions for improvements:
 
-- **Search existing issues**: Before submitting a new issue, please check if it has already been reported.
-- **Create a new issue**: If it’s a new issue, create one and provide detailed information such as steps to reproduce, expected and actual results, and any relevant screenshots or logs.
-- **Link to related tasks**: If your issue is related to any of the [TODOs](#https://github.com/Shayan-Ghani/boundary-vault-stack/tree/main/#to-do), please reference the corresponding task.
+- **Search Existing Issues**: Before submitting a new issue, check if it has already been reported.
+- **Create a New Issue**: If it’s a new issue, provide detailed information such as steps to reproduce, expected vs. actual results, and any relevant screenshots or logs.
+- **Link to Related Tasks**: If your issue relates to any of the [TODOs](https://github.com/Shayan-Ghani/boundary-vault-stack/tree/main/#to-do), reference the corresponding task.
+
+### Commit Messages
+
+**Use Conventional Commits**: The project follows [semantic versioning](https://semver.org/) to ensure proper releases. Start your commits with a prefix such as `fix:`, `feat:`, `chore:`, or `doc:`.
+
+- **Imperative Mood**: Write commit messages as commands (e.g., "Add Vagrantfile for VM provisioning").
+- **Be Concise but Descriptive**: Provide enough detail to understand the change.
+- **Commit Message Conventions**: Use `doc:` for any changes related to documentation.
 
 ### Submitting Pull Requests
 
 When submitting pull requests (PRs):
 
-1. **Create a branch**: Create a new branch for your feature or bug fix. Avoid working directly on the `main` branch.
+1. **Create a Branch**: Create a new branch for your feature or bug fix. Avoid working directly on the `main` branch.
     ```bash
     git checkout -b feature/your-feature-name
     ```
 
-2. **Make atomic commits**: Ensure each commit is focused and addresses a single change by Conforming to the Commit Messages section.
+2. **Make Atomic Commits**: Ensure each commit is focused and addresses a single change, following the Commit Messages section.
 
-3. **Follow the code style guidelines**: Ensure your code adheres to the project's code style and best practices.
+3. **Follow Best Practices**: Ensure your code adheres to the project's best practices.
 
-4. **Test your changes**: Run tests and ensure your changes do not break the existing code.
+4. **Test Your Changes**: Run tests and ensure your changes do not break existing code.
 
-5. **Update documentation**: If your change requires documentation updates, ensure these are included in your PR.
+5. **Update Documentation**: If your change requires documentation updates, include them in your PR. Use the `documentation` label and provide additional context in the PR description.
 
 6. **Submit the PR**: Push your branch to GitHub and open a pull request against the `main` branch. Link the PR to the corresponding issue(s).
 
 ### Code Style and Best Practices
 
-- **Use meaningful variable and function names**.
-- **Keep functions small and focused**: Each function should perform a single task.
-- **DRY (Don’t Repeat Yourself)**: Reuse code where possible.
-- **Comment your code**: Provide comments where the code is not self-explanatory.
-- **Follow best practices**: For Terraform, Ansible, and Shell Scripting, refer to the [Guidelines for Specific Tasks](#guidelines-for-specific-tasks).
-
-### Commit Messages
-
-- **Use imperative mood**: Write commit messages as if you are commanding the code to do something (e.g., "Add Vagrantfile for VM provisioning").
-- **Be concise but descriptive**: Provide enough detail to understand the change.
-
-#### Conventions
-  - start your commit with `doc:` in case of any change in wiki.
-  - start your commit with `closes #issue_number :` if your commit closes an issue.
-
+- **Use Meaningful Names**: Choose descriptive names for variables and tasks.
+- **Keep Tasks Small and Focused**: Each function should perform a single task.
+- **DRY (Don’t Repeat Yourself)**: Reuse code wherever possible.
+- **Comment Your Code**: Add comments where the code is not self-explanatory.
+- **Adhere to Best Practices**: Refer to the [Guidelines for Specific Tasks](#guidelines-for-specific-tasks) for Terraform, Ansible, and Shell Scripting.
 
 ## Guidelines for Specific Tasks
 
 ### Terraform
 
-- **State management**: Ensure you properly configure remote state management, especially when working on the tasks related to the remote backend.
-- **Output values**: Enhance output values to make them more informative and useful.
+- **State Management**: Configure remote state management properly, especially when working with remote backends.
+- **Output Values**: Make output values informative and useful.
+- **Avoid Unnecessary Loops**: Minimize the use of `foreach` and loops for variables, and avoid hardcoding values.
 
 ### Ansible
 
-- **Environment variables**: Use the `environment` attribute for declaring environment variables in roles.
-- **Role organization**: Keep roles modular and reusable.
+- **Role Organization**: Keep roles modular and reusable.
+- **Handlers and Utilities**: Use [handlers](./ansible/handlers/) and [utilities](./ansible/utils/) for frequently repeated tasks.
 
 ### Shell Scripting
 
-- **Logging**: Implement a consistent logging mechanism across all shell scripts. Use a custom logger function as outlined in the TODOs.
-- **Error handling**: Ensure scripts handle errors gracefully and provide informative messages.
+- **Logging**: Implement consistent logging across all shell scripts. Use a custom logger function as outlined in the TODOs.
+- **Error Handling**: Ensure scripts handle errors gracefully and provide informative messages.
 
 ### CI/CD
 
 - **GitHub Actions**: Contribute to the existing CI/CD pipeline by implementing automated testing, linting, and security scans for pull requests.
 
-### Testing
-
-- **Implement Ansible Molecule test cases**: For Ansible roles, write Molecule test scenarios to ensure your roles work as expected.
-- **Automated testing**: Contribute to the CI/CD pipeline by writing GitHub Actions workflows that automate testing.
-
 ## Communication
 
-- **Stay updated**: Regularly check for updates on the project and communicate with the maintainers for any significant contributions.
-- **Respectful collaboration**: Follow a code of conduct that fosters a respectful and inclusive environment.
+- **Stay Updated**: Regularly check for project updates and communicate with maintainers about significant contributions.
+- **Respectful Collaboration**: Follow the code of conduct to maintain a respectful and inclusive environment.
 
 ## License
 
 By contributing to this project, you agree that your contributions will be licensed under the project's [license](./LICENSE).
 
 ---
 
-Thank you for your interest in contributing to the Hashicorp Boundary and Vault Stack! We look forward to your contributions.
+Thank you for your interest in contributing to the HashiCorp Boundary and Vault Stack! We look forward to your contributions.

README.md

@@ -1,82 +1,75 @@
-# Hashicorp Boundary and Vault Stack
-Deploy Self-Hosted HCP Vault and Boundary using End-To-End automation.
-
-## What This Project Offers
-By providing a comprehensive and hands-on experience in Infrastructure as Code (IaC) and Configuration Management along with creating vital deliverables such as documentation and diagrams, this project simulates a real-world infrastructure development that emphasizes End-to-End automation, enabling DevOps Engineers to collaborate and deliver a reliable and production-ready stack to the end-users.
-
-## How To Use
-**First, make sure you have [READ THE DOCUMENTATION](./artifacts/wiki.md) for instructions on how the stack and Hashicorp Boundary/Vault work.**
-
-**See a thorough [diagram of the automation workflow big picture](https://linktw.in/nWgoiO).**
+# HashiCorp Boundary and Vault Stack
 
+Deploy a Self-Hosted HCP Vault and Boundary stack using end-to-end automation.
 
+## What This Project Offers
 
-1. To begin with, create your own `tfvars` based on the sample provided in [boundary](./boundary/terraform/terraform.tfvars.sample) and [vault](./vault/terraform/terraform.tfvars.sample) or simply remove the leading .sample extension to apply the sample values.
+This project provides a comprehensive, hands-on experience in Infrastructure as Code (IaC) and Configuration Management. It simulates a real-world infrastructure environment with a focus on end-to-end automation, enabling DevOps engineers to collaboratively deliver a reliable, production-ready stack. Key deliverables include detailed documentation and diagrams.
 
-2. Initialize the process by running `start.sh` script in your desired environment:
- ```bash
- #run in dev:
-        ./start.sh -e development
- ```
+## How to Use
 
-*If you need further assistance on the exit/return code and configurations, check out [ wiki ](./artifacts/wiki.md).*
+1. **Read the Documentation**: Before getting started, ensure you have thoroughly reviewed the [project documentation](./artifacts/wiki.md) and the [automation workflow diagram](https://linktw.in/nWgoiO).
 
-3. You'll be prompted to Enter the vault-password to decrypt ansible-vault encrypted files (e.g inventory.ini).
+2. **Configure Variables**: Create your own `tfvars` file based on the samples provided in the [Boundary](./boundary/terraform/terraform.tfvars.sample) and [Vault](./vault/terraform/terraform.tfvars.sample) directories. Alternatively, you can remove the `.sample` extension from the provided sample files to use the default values.
 
-**The `ansible-vault-pass` is `BVSTACK`. This is for the sake of simplicity and sample, make sure you use a strong password for your ansible vault encrypted files.**
+3. **Run the Start Script**: Begin the setup by running the `start.sh` script in your desired environment:
+    ```bash
+    # Run in development:
+    ./start.sh -e development
+    ```
 
-## TO-DO
-> Terraform ....
+    For further assistance on exit/return codes and configurations, refer to the [documentation](./artifacts/wiki.md).
 
-> NOTE
-> Implement all of the provisioners inside provision Directory and Ansible Role 
+4. **Enter Vault Password**: You will be prompted to enter the Vault password to decrypt Ansible Vault-encrypted files (e.g., `inventory.ini`).
 
-- [ ] Add a **Vagrantfile** to provision a VM using the **Vagrant** provider of your choice based on [ specs ](./provision/specs.txt) with `Terraform`.
+    **Note**: The default `ansible-vault-pass` is `BVSTACK`. This is provided for simplicity in the sample; ensure you use a strong password for your Ansible Vault-encrypted files.
 
-- [ ] Using `Terraform` **AWS** provider provision an **EC2** instance based on [ specs ](./provision/specs.txt) + additional required configuration.
+## To-Do List
 
-- [ ] Using `Terraform` **Azure** provider provision an Azure VMs instace based on [ specs ](./provision/specs.txt) + additional required configuration.
+### Terraform
 
-- [ ] Using `Terraform` **Vsphere** provider, provision a vm on an ESXI server based on [ specs ](./provision/specs.txt). 
+- [ ] Add a **Vagrantfile** to provision a VM using the **Vagrant** provider of your choice, based on the [specifications](./provision/specs.txt).
+- [ ] Provision an **EC2** instance using the **AWS** provider based on the [specifications](./provision/specs.txt) and additional required configurations.
+- [ ] Provision an **Azure** VM using the **Azure** provider based on the [specifications](./provision/specs.txt) and additional required configurations.
+- [ ] Provision a VM on an ESXi server using the **vSphere** provider based on the [specifications](./provision/specs.txt).
+- [ ] Add a remote backend option for Boundary and Vault.
+- [ ] Implement additional Vault authentication methods.
+- [ ] Enhance Terraform output values for both Boundary and Vault.
+- [ ] Implement Policy as Code (PaC) to validate Terraform policies.
 
+### Packer
 
-- [ ] Add `Terraform` Remote Backend option for Boundary and Vault. 
-- [ ] Add other Vault auth methods using `Terraform`.
-- [ ] Enchance `Terraform Output` values for both Boundary and Vault
-- [ ] Implement `Policy as Code (PaC)` to validate `Terraform` policies.
+- [ ] Add a Packer custom image template for VMware vSphere using the [specifications](./provision/specs.txt).
 
-> Packer ...
+### Ansible
 
-- [ ] Add Packer custom image template for VMware Vsphere using [ specs ](./provision/specs.txt).
+- [ ] Install and configure Terraform on the **control node** using the `prepare_env` role.
+- [ ] Install and configure Docker on **target (managed) nodes** using the `prepare_env` role.
+- [ ] Template `tfvars` files to handle specific variables for both Boundary and Vault Terraform providers.
+- [ ] Create a well-organized Ansible template for Vault and Boundary configurations.
+- [ ] Update environment variable declarations in Ansible roles to use the `environment` attribute instead of inline definitions in the `shell` module.
+- [ ] Add proper configurations to serve the stack as a reverse proxy in the `serve` directory (tool optional).
+- [ ] Update `boundary.yml` to use environment variables instead of hardcoding, then manage the export of these variables with Ansible.
+- [ ] Convert Docker Compose files to corresponding Ansible modules using the `community.docker.docker_container` collection as an optional deployment method.
+- [ ] Implement Ansible Molecule scenarios to test different aspects of your roles.
+- [ ] Choose which provider to provision based on a user-defined or environment variable when handling provisions with Ansible.
 
-> Ansible ... 
+### CI/CD
 
-- [ ] Install and configure `Terraform` on the **control node** (`prepare_env` role).
-- [ ] Install and configure `Docker` on **target (managed) node(s)** (`prepare_env` role).
-- [ ] Optionally, install boundary and vault on **admins** node(s) Based on `STACK_BIN=true/false` Environment variable. 
-- [ ] Template `tfvars` file to handle specific variables for both boundary and vault terraform providers.
-- [ ] Create a well-organized `Ansible` template for Vault and boundary configurations.
-- [ ] Update environment variable declaration through `Ansible` roles to use `environment` attribute instead of inline definition in `shell` module.
-- [ ] Add proper configurations to serve the stack as a reverse proxy in the `serve` directory(the tool is optional).
-- [ ] Update `boundary.yml` to use ENV variables instead of hardcoding then handle the export of the env variables with `Ansible`.
-- [ ] Using `Ansible` `community.docker.docker_container` collection, convert docker-compose files to the corresponding `Ansible` module as an optional deployment method.
-- [ ] Implement Ansible `Molecule` case scenarios to test different aspects of your roles.
-- [ ] When handling Provisions with `Ansible`, Choose which Provider to provision Based on a User-Defined or Environment variable.
+- [ ] Implement automated testing using GitHub Actions for pull requests.
 
-> CI/CD ....
+### Shell Scripting
 
-- [ ] Implement automated testing using GitHub actions for pull requests. 
+- [ ] Write a custom logger function and implement it throughout all shell scripts for better error handling and logging (in the `log` directory).
+- [ ] Use `case` statements instead of `if` for argument handling in `init.sh`.
+- [ ] Update `start.sh` to prompt for the Ansible Vault password once and use it for all operations.
+- [ ] Replace sleep commands in `start.sh` with the appropriate Ansible `wait_for` modules.
+- [ ] Remove the Vault root token in the `cleanup` script.
 
-> Shell Scripting ... 
+## Contribution
 
-- [ ] Write a `Custom Logger` function and use it throughout all shell scripts for better error handling and logging (`log` directory).
-- [ ] Use `case` instead of if for argument handling in `init.sh`.
-- [ ] Make `start.sh` ask for the ansible-vault password once and use it for all.
-- [ ] Update the sleep commands in the `start.sh` to use `Ansible` wait_for modules instead.
-- [ ] Remove vault root token in `cleanup`.
+All contributions are welcome! Please read the [Contributing Guidelines](./CONTRIBUTING.md) for more information.
 
-## Contribution
-all types of contribution is welcomed, read [`Contribution.md`](./Contributing.md) for more information.
+## Credit and Maintenance
 
-## Credit and Maintainance
-**Copyright © 2024 [Shayan Ghani](https://github.com/Shayan-Ghani) [email protected]**
+**Copyright © 2024 [Shayan Ghani](https://github.com/Shayan-Ghani) - [email protected]**