docs: improve grammar and link to image (#31)

* docs: improve grammar and link to image

* docs: improve grammar on readme

* docs: update .gitignore

Author: ssliman

.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 .idea/
 .history/
 .vscode
@@ -112,4 +113,4 @@ venv.bak/
 *.iml
 
 _lint.yaml
-values.dev.yaml
+values.dev.yaml

README.md

@@ -1,7 +1,7 @@
 # Piper
 ![alt text](https://www.rookout.com/wp-content/uploads/2022/10/ArgoPipeline_1.0_Hero.png.webp?raw=true)
 
-Welcome to Piper! Piper is open source project that aimed at providing multibranch pipeline functionality to Argo Workflows, allows users to create distinct Workflows based on Git branches.
+Welcome to Piper! Piper is an open-source project aimed at providing multibranch pipeline functionality to Argo Workflows, allowing users to create distinct Workflows based on Git branches.
 
 ## Table of Contents
 
@@ -14,8 +14,8 @@ Welcome to Piper! Piper is open source project that aimed at providing multibran
 
 ## Getting Started
 
-Piper configures a webhook in git provider and listens to the webhooks sends. It will create a Workflow CRD out of branches that contains `.workflows` folder.
-This folder should contain declarations of the templates and main DAG that will be running.
+Piper configures a webhook in the git provider and listens to the webhooks sent. It will create a Workflow CRD out of branches that contain a `.workflows` folder.
+This folder should contain declarations of the templates and the main DAG that will be running.
 Finally, it will submit the Workflow as a K8s resource in the cluster.
 To access more detailed explanations, please navigate to the [Documentation site](https://piper.quickube.com).
 
@@ -34,8 +34,8 @@ If you encounter any issues or bugs while using Piper, please help us improve by
 ## How to Contribute
 
 If you're interested in contributing to this project, please feel free to submit a pull request. We welcome all contributions and feedback.
-Please check out our [Contribution guidelines for this project](docs/CONTRIBUTING.md)
+Please check out our [contribution guidelines for this project](docs/CONTRIBUTING.md).
 
 ## License
 
-This project is licensed under the Apache License. Please see the [LICENSE](LICENSE) file for details.
+This project is licensed under the Apache License. Please see the [LICENSE](LICENSE) file for details.

docs/CONTRIBUTING.md

@@ -16,7 +16,7 @@ git checkout -b my-feature
 ```bash
 git commit -s -m "fix: Add new feature"
 ```
-* please make sure you commit as described in [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/)
+* Please make sure you commit as described in [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/)
 6. Push your changes to your forked repository:
 ```bash
 git push origin my-feature
@@ -28,16 +28,16 @@ git push origin my-feature
 We welcome and appreciate contributions from the community. If you have developed a new feature, improvement, or bug fix for Piper, follow these steps to submit a pull request:
 
 1. Make sure you have forked the Piper repository and created a new branch for your changes. Checkout [How To Contribute](#How-to-contribute).
-2. commit your changes and push them to your forked repository.
+2. Commit your changes and push them to your forked repository.
 3. Go to the Piper repository on GitHub.
 4. Click on the "New Pull Request" button.
-5. Select your branch and provide a [descriptive title](#pull-request-nameing) and detailed description of your changes.
+5. Select your branch and provide a [descriptive title](#pull-request-naming) and a detailed description of your changes.
 6. If your pull request relates to an open issue, reference the issue in the description using the GitHub issue syntax (e.g., Fixes #123).
 7. Submit the pull request, and our team will review your changes. We appreciate your patience during the review process and may provide feedback or request further modifications.
 
 ### Pull Request Naming
 
-The name should follow conventional commit naming. 
+The name should follow Conventional Commits naming.
 
 ## Coding Guidelines
 
@@ -49,8 +49,8 @@ To maintain a consistent codebase and ensure readability, we follow a set of cod
 * Use meaningful variable and function names.
 * Make sure your code is properly formatted and free of syntax errors.
 * Run tests locally.
-* Check that the feature documented.
-* Add new packages only if necessary and already existing one, can't be used.
+* Check that the feature is documented.
+* Add new packages only if necessary and if an already existing one can't be used.
 * Add tests for new features or modification.
 
 ## Helm Chart Development
@@ -76,28 +76,28 @@ brew install helm
 ```bash
 brew install kubectl
 ```
-3. isntall docker
+3. install docker
 
 4. install ngrok
 ```bash
 brew install ngrok
 ```
-6. install 5
+5. install kind
 ```bash
 brew install kind
 ```
 
 Deployment:
-1. make sure docker are running. 
-2. create tunnel with ngrok using `make ngrok`, save the `Forwarding` address.
-3. create `values.dev.yaml` file that contains subset of chart's `value.yaml` file. check [example of values file](https://github.com/quickube/piper/tree/main/examples/template.values.dev.yaml) rename it to `values.dev.yaml` and put in root directory.
-4. use `make deploy`. it will do the following:
-     * deploy a local registry as container
-     * deploy a kind cluster as container with configuration
-     * deploy nginx reverse proxy in the kind cluster
-     * deploy Piper with the local helm chart
-5. validate using `curl localhost/piper/healthz`.
+1. Make sure Docker is running.
+2. Create a tunnel with ngrok using `make ngrok`, and save the `Forwarding` address.
+3. Create a `values.dev.yaml` file that contains a subset of the chart's `values.yaml` file. Check the [example of values file](https://github.com/quickube/piper/tree/main/examples/template.values.dev.yaml), rename it to `values.dev.yaml`, and put it in the root directory.
+4. Use `make deploy`. It will do the following:
+   * Deploy a local registry as a container
+   * Deploy a kind cluster as a container with configuration
+   * Deploy nginx reverse proxy in the kind cluster
+   * Deploy Piper with the local helm chart
+5. Validate using `curl localhost/piper/healthz`.
 
 ## Debugging
 
-For debugging the best practice is to use Rookout. To enable this function pass a Rookout token in the chart `rookout.token` or as existing secret `rookout.existingSecret`
+For debugging, the best practice is to use Rookout. To enable this function, pass a Rookout token in the chart `rookout.token` or as an existing secret `rookout.existingSecret`.

docs/configuration/environment_variables.md

@@ -1,64 +1,66 @@
 ## Environment Variables
 
 Piper uses the following environment variables to configure its functionality.
-The helm chart populates them using [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file
+The helm chart populates them using the [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file.
 
 ### Git
 
 - GIT_PROVIDER
-  The git provider that Piper will use, possible variables: GitHub | Gitlab | Bitbucket
+  The git provider that Piper will use, possible variables: GitHub | GitLab | Bitbucket
 
 * GIT_TOKEN
   The git token that will be used to connect to the git provider.
 
 - GIT_URL
-  the git url that will be used, only relevant when running gitlab self hosted
+  The git URL that will be used, only relevant when running GitLab self-hosted.
 
 - GIT_ORG_NAME
   The organization name.
 
 * GIT_ORG_LEVEL_WEBHOOK
-  Boolean variable, whether to config webhook at the organization level. Defaults to `false`.
+  Boolean variable, whether to configure the webhook at the organization level. Defaults to `false`.
 
 * GIT_WEBHOOK_REPO_LIST
-  List of repositories to configure webhooks to.
+  List of repositories to configure webhooks for.
 
 * GIT_WEBHOOK_URL
-  URL of Piper ingress, to configure webhooks.
+  URL of Piper ingress to configure webhooks.
 
 * GIT_WEBHOOK_AUTO_CLEANUP
-  Boolean variable that, if true, will cause Piper to automatically cleanup all webhooks that it creates when they are no longer necessary.
-  Notice that there is a race condition between a pod that is being terminated and the new one being scheduled.
+  Boolean variable that, if true, will cause Piper to automatically clean up all webhooks it creates when they are no longer necessary.
+  Note that there is a race condition between a pod being terminated and a new one being scheduled.
 
 * GIT_ENFORCE_ORG_BELONGING
-  Boolean variable that, if true, will cause Piper to enforce organizational belonging of git event creator. Defaults to `false`.
+  Boolean variable that, if true, will cause Piper to enforce the organizational belonging of the git event creator. Defaults to `false`.
 
 * GIT_FULL_HEALTH_CHECK
-  Boolean variable that, if true, enables full health checks on webhooks. A full health check contains expecting and validating ping event from a webhook.
-  Doesn't work for Bitbucket, because the API call doesn't exist on that platform.
+  Boolean variable that, if true, enables full health checks on webhooks. A full health check involves expecting and validating a ping event from a webhook.
+  This doesn't work for Bitbucket because the API call doesn't exist on that platform.
 
 ### Argo Workflows Server
 
 * ARGO_WORKFLOWS_TOKEN
   This token is used to authenticate with the Argo Workflows server.
 
 * ARGO_WORKFLOWS_ADDRESS
-  The address of Argo Workflows Server.
+  The address of the Argo Workflows server.
 
 * ARGO_WORKFLOWS_CREATE_CRD
-  Boolean variable that deterines whether to directly send Workflows instructions or create a CRD in the Cluster.
+  Boolean variable that determines whether to directly send Workflows instructions or create a CRD in the Cluster.
 
 * ARGO_WORKFLOWS_NAMESPACE
   The namespace of Workflows creation for Argo Workflows.
 
 * KUBE_CONFIG
-  Used to configure Argo Workflows client with local kube configurations.
+  Used to configure the Argo Workflows client with local kube configurations.
 
 ### Rookout
 
 * ROOKOUT_TOKEN
-  The token used to configure Rookout agent. If not provided, will not start the agent.
+  The token used to configure the Rookout agent. If not provided, the agent will not start.
+
 * ROOKOUT_LABELS
-  The labels to label instances at Rookout, defaults to "service:piper"
+  The labels to label instances in Rookout, defaults to "service:piper".
+
 * ROOKOUT_REMOTE_ORIGIN
-  The repo URL for source code fetching, default:"https://github.com/quickube/piper.git".
+  The repo URL for source code fetching, defaults to "https://github.com/quickube/piper.git".

docs/configuration/health_check.md

@@ -1,8 +1,8 @@
 ## Health Check
 
-currently not supported for gitlab / bitbucket
+Currently not supported for GitLab / Bitbucket
 
-The following examples shows a health check being executed every 1 minute as configured in the helm chart under `livenessProbe`, and triggered by `/healthz` endpoint:
+The following example shows a health check being executed every 1 minute as configured in the helm chart under `livenessProbe`, and triggered by the `/healthz` endpoint:
 
 ```yaml
 livenessProbe:
@@ -19,15 +19,15 @@ livenessProbe:
 
 The mechanism for checking the health of Piper is:
 
-1. Piper set health status of all webhooks to not-healthy.
+1. Piper sets the health status of all webhooks to not healthy
 
-2. Piper requests ping from all the webhooks configured.
+2. Piper requests a ping from all the configured webhooks.
 
-3. Git Provider send ping to `/webhook` endpoint, this will set the health status to `healthy` with timeout of 5 seconds.
+3. The Git provider sends a ping to the `/webhook` endpoint, which will set the health status to `healthy` with a timeout of 5 seconds.
 
-4. Piper check the status of all webhooks configured.
+4. Piper checks the status of all configured webhooks.
 
 Therefore, the criteria for health checking are:
 
 1. The registered webhook exists.
-2. The webhook send a ping in 5 seconds.
+2. The webhook sends a ping within 5 seconds.

docs/getting_started/installation.md

@@ -1,7 +1,7 @@
 ## Installation
 
 You must deploy Piper to a cluster with a pre-existing Argo Workflows deployment.
-Piper will create a CRD that Argo Workflows will pick, so install or configure Piper to create those CRDs in the right namespace.
+Piper will create a CRD that Argo Workflows will pick up, so install or configure Piper to create those CRDs in the right namespace.
 
 Please check out [values.yaml](https://github.com/quickube/piper/tree/main/helm-chart/values.yaml) file of the helm chart configurations.
 
@@ -36,11 +36,11 @@ Piper will use git to fetch the `.workflows` folder and receive events using web
 
 To pick which git provider you are using provide `gitProvider.name` configuration in helm chart (Currently we only support GitHub and Bitbucket).
 
-Also configure you organization (Github), workspace (Bitbucket) or group (Gitlab) name using `gitProvider.organization.name` in helm chart.
+Also configure your organization (GitHub), workspace (Bitbucket) or group (GitLab) name using `gitProvider.organization.name` in helm chart.
 
 #### Git Token Permissions
 
-The token should have access for creating webhooks and read repositories content.</br>
+The token should have access to create webhooks and read repository content.</br>
 <b>For GitHub</b>, configure `admin:org` and `write:org` permissions in Classic Token. </br>
 <b>For Bitbucket</b>, configure `Repositories:read`, `Webhooks:read and write` and `Pull requests:read` permissions (for multiple repos use workspace token). </br>
 <b>For Gitlab</b>, configure `read_api`, `write_repository` and `api` (for multiple repos use group token with owner role). </br>
@@ -50,38 +50,38 @@ The token should have access for creating webhooks and read repositories content
 The git token should be passed as secret in the helm chart at `gitProvider.token`.
 The token can be passed as parameter via helm install command using `--set piper.gitProvider.token=YOUR_GIT_TOKEN`
 
-Alternatively, you can consume an already existing secret by configuring `piper.gipProvider.existingSecret`.
-The key should have the name `token`. You can be create a Secret using this command:
+Alternatively, you can use an already existing secret by configuring `piper.gipProvider.existingSecret`.
+The key should be named token `token`. You can create a Secret using this command:
 
 ```bash
 kubectl create secret generic piper-git-token --from-literal=token=YOUR_GIT_OKEN
 ```
 
 #### Webhook creation
 
-Piper will create a webhook configuration for you, for the whole organization or for each repo you configure.
+Piper will create a webhook configuration for you, either for the whole organization or for each repo you configure.
 
 Configure `piper.webhook.url` with the address of Piper that you exposed using an Ingress or Service with `/webhook` postfix.
 
 For organization level configuration: `gitProvider.webhook.orgLevel` to `true`.
 
 For granular repo webhook provide list of repos at: `gitProvider.webhook.repoList`.
 
-Piper implements graceful shutdown, it will delete all the webhooks when terminated.
+Piper implements a graceful shutdown; it will delete all the webhooks when terminated.
 
 #### Status check
 
-Piper will handle status checks for you.
-It will notify the GitProvider for the status of Workflow for specific commit that triggered Piper.
+Piper will handle status checks for you. 
+It will notify the GitProvider of the status of the Workflow for the specific commit that triggered Piper.
 For linking provide valid URL of your Argo Workflows server address at: `argoWorkflows.server.address`
 
 ---
 
 ### Argo Workflow Server (On development)
 
-Piper will use REST API to communicate with Argo Workflows server for linting or for creation of workflows (ARGO_WORKFLOWS_CREATE_CRD). Please follow this [configuration](https://argoproj.github.io/argo-workflows/rest-api/).
+Piper will use the REST API to communicate with the Argo Workflows server for linting or creating workflows.
 
-To lint the workflow before submitting it, please configure the internal address of Argo Workflows server (for example, `argo-server.workflows.svc.cluster.local`) in the field: `argoWorkflows.server.address`. Argo will need a [token](https://argoproj.github.io/argo-workflows/access-token/) to authenticate. please provide the secret in `argoWorkflows.server.token`, Better to pass as a references to a secret in the field `argoWorkflows.server.token`.
+To lint the workflow before submitting it, please configure the internal address of Argo Workflows server (for example, `argo-server.workflows.svc.cluster.local`) in the field: `argoWorkflows.server.address`. Argo will need a [token](https://argoproj.github.io/argo-workflows/access-token/) to authenticate. Please provide the secret in `argoWorkflows.server.token`. It is better to pass it as a reference to a secret in the field `argoWorkflows.server.token`.
 
 #### Skip CRD Creation (On development)
 

docs/index.md

@@ -1,19 +1,19 @@
 # Introduction
 
-<p align="center">
-  <img src="https://www.quickube.com/wp-content/uploads/2022/10/ArgoPipeline_1.0_Hero.png.webp?raw=true" />
+<p>
+  <img src="https://www.rookout.com/wp-content/uploads/2022/10/ArgoPipeline_1.0_Hero.png.webp?raw=true"  alt="ArgoPipeline"/>
 </p>
 
 Welcome to Piper!
 
-Piper is an open source project that aimed at providing multibranch pipeline functionality to Argo Workflows. This allows users to create distinct Workflows based on Git branches. We supports GitHub and Bitbucket.
+Piper is an open-source project aimed at providing multibranch pipeline functionality to Argo Workflows. This allows users to create distinct Workflows based on Git branches. We support GitHub and Bitbucket.
 
 ## General Explanation
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/quickube/piper/main/docs/img/flow.svg" />
+<p>
+  <img src="https://raw.githubusercontent.com/quickube/piper/main/docs/img/flow.svg"  alt="flow"/>
 </p>
 
-Piper handles the hard work of configuring multibranch pipelines for us! At initialization, it will load all configuration and create a webhook in repository or organization scope. Then, for each branch that has a `.workflows` folder, Piper will create a Workflow CRD out of the files in this folder. Finally, when Piper detects changes in the repository via the webhook, it triggers the workflows that match the branch and event.
+Piper handles the hard work of configuring multibranch pipelines for us! At initialization, it will load all configuration and create a webhook in the repository or organization scope. Then, for each branch that has a `.workflows` folder, Piper will create a Workflow CRD out of the files in this folder. Finally, when Piper detects changes in the repository via the webhook, it triggers the workflows that match the branch and event.
 
-![type:video](./img/piper-demo-1080.mp4)
+![type:video](./img/piper-demo-1080.mp4)