Enhance the docs for 'deploy.yml'

docs/concepts/deploy.yml.md

@@ -2,15 +2,16 @@
 sidebar_position: 2
 ---
 
-# deploy.yml
+Gitploy provides the way users can configure pipelines by a simple file, such as **deployment trigger**, **deployment safety**, and **deploying** to a runtime environment🚀. The syntax is designed to be easy to read and expressive so that anyone can understand the pipeline. You can check the [documentation](../references/deploy.yml.md) for the syntax of the file.
 
-Gitploy configures a pipeline with a simple, easy‑to‑read file that you commit to your git repository. The default path is `deploy.yml` at the root directory, but you can replace the file path in the settings tab of Gitploy. You can check the [documentation](../references/deploy.yml.md) for the specification of the configuration file and also references [Use Cases](../tasks/usecases.md). 
+Pipelines are configured by placing a `deploy.yml` file in the root of your git repository. And if you want to change the file path, you can do it on the settings page.  
 
 *⚠️ Note that the configuration file must be at the head of the default branch.* 
 
 ## Quick Start
+If you want to get started quickly, you should click the *New Configuration* link, copy the `deploy.yml` file, and push it into your git repository. Then you can find the `production` environment in the deploy tab.
 
-If you want to get started quickly, you should click the *New Configuration* link, copy the `deploy.yml` file, and push it into your git repository. Then you can find the `production` environment in Gitploy.
+![Quick Start](../../static/img/docs/quickstart.png)
 
 ```yaml title="deploy.yml"
 envs:
@@ -20,58 +21,36 @@ envs:
     # required_context: []
 ```
 
-![Quick Start](../../static/img/docs/quickstart.png)
+## Deployment Trigger
 
-## Features
-### Multi Environment
+### Auto Deploy
+Gitploy provides continuous delivery basically, but it also provides **continuous deployment**. The deployment will be triggered automatically if any new push events are detected from GitHub.
+ To enable continuous deployment, you should configure the `auto_deploy_on` field. Gitploy triggers a deployment when a `ref` of the push event is matched with the field.
 
-For multi-environment, Gitploy provides you can make different pipelines for each environment, respectively. The configuration has to be defined under the `envs` field. The following example shows each environment has a different configuration.
+This configuration also supports a regular expression to match with the specific pattern. It allows you to deploy on any tag (i.e., `refs/tags/.*`) or to match specific branches (i.e., `refs/heads/(main|master)`).
 
 ```yaml title="deploy.yml"
 envs:
-  # Development environment
-  - name: development
-    auto_merge: false
-    required_contexts: []
-
-  # Production environment
   - name: production
-    auto_merge: true
-    required_contexts: 
-      - test
-      - docker-image
+    auto_deploy_on: refs/heads/main
 ```
 
-### Parameters of GitHub deployment API
+## Deployment safety
 
-Internally, Gitploy posts a deployment to GitHub [deployments API](https://docs.github.com/en/rest/reference/repos#create-a-deployment) with parameters from the configuration file. These parameters help you can verify the artifact before you start to deploy.  The configuration provides fields to set all parameters of GitHub deployment API. You can check the [document](../references/deploy.yml.md) for the detail.
-
-```yaml title="deploy.yml"
-envs:
-  - name: production
-    task: deploy:lambda
-    description: Start deploying to the production.
-    auto_merge: false
-    required_contexts:
-      - test
-      - integration-test
-    production_environment: true
-```
+### Deployable Ref
 
-### Auto Deploy
-
-Gitploy provides not only manual deployment but also auto-deployment. Gitploy is listening for the push event dispatched from GitHub and triggers to deploy automatically when the ref is matched with the `auto_deploy_on` of the configuration file. 
+The `ref` can be any named branch, tag, or SHA. But sometimes, a `ref` must be specific branches or tags. You can verify a `ref` matched with the format by configuring the `deployable_ref` field. And this configuration also supports a regular expression.
 
 ```yaml title="deploy.yml"
 envs:
   - name: production
-    auto_deploy_on: refs/heads/main
-    production_environment: true
+    deployable_ref: "v.*"
 ```
 
 ### Deploy Freeze Window
+If you want to prevent deployments for a particular period, such as during a planned vacation period or out of working time, you can configure the `frozen_windows` field. During a deploy freeze period, users can not execute any deployment. 
 
-Gitploy support to add a window to prevent unintended deployment for the environment. You can freeze a window periodically by a cron expression.
+And this configuration uses the cron expression to handle repetitive periods. You can check the detail in the [documentation](../references/deploy.yml.md).
 
 ```yaml title="deploy.yml"
 envs:
@@ -88,13 +67,30 @@ envs:
 ```
 
 ### Review
-
-Gitploy provides the review process. You can list up to users on the configuration file. You can check the [document](./review.md) for the detail.
+If you require a specific person, such as a service owner or product manager, to review what is deployed before deployment, you can configure the `review` field. You can list up users as reviewers under the `review` field. Then Gitploy requests a review to users by sending a notification when a deployment is triggered.
 
 ```yaml title="deploy.yml"
 envs:
   - name: production
     review:
       enabled: true
-      reviewers: ["ocotocat", "noah"]
+      reviewers: ["ocotocat", "manager"]
 ```
+
+## Deploy 🚀
+
+### Parameters of GitHub deployment API
+As the 'How it works' documentation mentioned, Gitploy sends a request by deployment API. You can configure all the parameters in a configuration file.
+
+```yaml title="deploy.yml"
+envs:
+  - name: production
+    task: deploy:lambda
+    description: Deploy to the production lambda.
+    auto_merge: false
+    required_contexts:
+      - test
+      - integration-test
+    production_environment: true
+```
+

docs/tasks/integration.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 ---
 
 # Integration

package.json

@@ -1,6 +1,6 @@
 {
   "name": "website",
-  "version": "0.0.0",
+  "version": "0.5.5",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",