Miscellaneous Doc updates (#510)

**What this PR does / why we need it**:  This PR implements a few small changes: 1. `.github/release.yml` - Adds a configuration for categorising changes in automatically generated release notes ([ref](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#example-configurations)) 2. `.github/workflows/pr-checks.yaml` - Makes labelling PRs mandatory ([ref](https://github.com/marketplace/actions/require-labels)). The full list of labels are [here](https://github.com/caraml-dev/merlin/labels). Only a subset of them, defined in the workflow file, are applicable to PRs. 3. Renames / reorganises the docs: ``` . ├── README.md ├── SUMMARY.md ├── developer // For dev docs ├── diagrams ├── images ├── maintainer // For maintainer docs └── user // For user docs ``` 4. Update the PR template to make the comments slightly more concise and add more sections The contents of the docs will be updated in a separate PR. **Which issue(s) this PR fixes**:  None **Does this PR introduce a user-facing change?**:  ```release-note NONE ``` **Checklist** - [ ] Added unit test, integration, and/or e2e tests - [ ] Tested locally - [x] Updated documentation - [ ] Update Swagger spec if the PR introduce API changes - [ ] Regenerated Golang and Python client if the PR introduce API changes
caraml-dev · Dec 21, 2023 · fe2e7c5 · fe2e7c5
1 parent f168838
commit fe2e7c5
Show file tree

Hide file tree

Showing 39 changed files with 90 additions and 58 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -5,20 +5,29 @@
 3. Make sure documentation is updated for your PR!
 
 -->
+# Description
+<!-- Briefly describe the motivation for the change. Please include illustrations where appropriate. -->
 
-**What this PR does / why we need it**:
-<!-- Explain here the context and why you're making the change. What is the problem you're trying to solve. --->
+# Modifications
+<!-- Summarize the key code changes. -->
 
-**Which issue(s) this PR fixes**:
-<!--
-*Automatically closes linked issue when PR is merged.
-Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`.
+# Tests
+<!-- Besides the existing / updated automated tests, what specific scenarios should be tested? Consider the backward compatibility of the changes, whether corner cases are covered, etc. Please describe the tests and check the ones that have been completed. Eg:
+- [x] Deploying new and existing standard models
+- [ ] Deploying PyFunc models
 -->
 
-Fixes #
+# Checklist
+- [ ] Added PR label
+- [ ] Added unit test, integration, and/or e2e tests
+- [ ] Tested locally
+- [ ] Updated documentation
+- [ ] Update Swagger spec if the PR introduce API changes
+- [ ] Regenerated Golang and Python client if the PR introduces API changes
 
-**Does this PR introduce a user-facing change?**:
+# Release Notes
 <!--
+Does this PR introduce a user-facing change?
 If no, just write "NONE" in the release-note block below.
 If yes, a release note is required. Enter your extended release note in the block below.
 If the PR requires additional action from users switching to the new release, include the string "action required".
@@ -29,11 +38,3 @@ For more information about release notes, see kubernetes' guide here: http://git
 ```release-note
 
 ```
-
-**Checklist**
-
-- [ ] Added unit test, integration, and/or e2e tests
-- [ ] Tested locally
-- [ ] Updated documentation
-- [ ] Update Swagger spec if the PR introduce API changes
-- [ ] Regenerated Golang and Python client if the PR introduce API changes
diff --git a/.github/release.yml b/.github/release.yml
@@ -0,0 +1,18 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+  categories:
+    - title: Breaking Changes 🛠
+      labels:
+        - breaking
+    - title: New Features 🎉
+      labels:
+        - enhancement
+    - title: Bug Fixes 🐞
+        - bug
+    - title: Documentation 📄
+        - documentation
+    - title: Other Changes
+      labels:
+        - "*"
diff --git a/.github/workflows/pr-checks.yaml b/.github/workflows/pr-checks.yaml
@@ -0,0 +1,16 @@
+name: Pull Request Labels
+on:
+  pull_request:
+    types: [opened, labeled, unlabeled, synchronize]
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: mheap/github-action-required-labels@v5
+        with:
+          mode: minimum
+          count: 1
+          labels: "breaking, bug, enhancement, documentation, maintenance" # Permissible PR labels
diff --git a/docs/README.md b/docs/README.md
@@ -40,3 +40,14 @@ The design of Merlin uses a few key concepts below, you should familiarize yours
 **Model Version Endpoint**: A model version endpoint is a way to obtain model inference results in real-time, over the network (HTTP). This endpoint is unique to each model version. Model endpoint will route to the model version endpoint in the background, when the associated model version is set to serving.
 
 **Environment**: The environment’s name is a user-facing property that will be used to determine the target Kubernetes cluster where a model will be deployed to. The environment has two important properties, name and Kubernetes cluster.
+
+## Getting Started
+
+To start learning about using Merlin, check out:
+{% page-ref page="../user/basics.md" %}
+
+To connect to an existing Merlin deployment, check out:
+{% page-ref page="../user/connecting-to-merlin/README.md" %}
+
+To start deploying Merlin, check out:
+{% page-ref page="../developer/deploying-merlin/README.md" %}
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -3,42 +3,41 @@
 ## Introduction
 
 * [Merlin Overview](README.md)
-* [Getting Started](getting-started/README.md)
 
 ## Connecting to Merlin
 
-* [Connection Methods](connecting-to-merlin/README.md)
-* [Python SDK](connecting-to-merlin/python-sdk.md)
-* [Merlin CLI](connecting-to-merlin/merlin-cli.md)
+* [Connection Methods](user/connecting-to-merlin/README.md)
+* [Python SDK](user/connecting-to-merlin/python-sdk.md)
+* [Merlin CLI](user/connecting-to-merlin/merlin-cli.md)
 
 ## User Guides
 
-* [Basic Concepts](user-guide/basics.md)
-    * [Create a Model](user-guide/model.md)
-    * [Create a Model Version](user-guide/model_version.md)
-    * [Model Version Endpoint](user-guide/model_version_endpoint.md)
-    * [Model Endpoint](user-guide/model_endpoint.md)
-    * [Model Deployment and Serving](user-guide/model_deployment_serving.md)
-    * [Delete a Model](user-guide/model_deletion.md)
-    * [Delete a Model Version](user-guide/model_version_deletion.md)
-* [Batch Prediction](user-guide/batch_prediction.md)
-* [Transformer](user-guide/transformer.md)
-    * [Standard Transformer](user-guide/standard_transformer.md)
-        * [Standard Transformer Expression](user-guide/transformer_expressions.md)
-        * [Standard Transformer for UPI](user-guide/standard_transformer_upi.md)
-    * [Custom Transformer](user-guide/custom_transformer.md)
-* [Examples](user-guide/examples/README.md)
-    * [Deploy Standard Models](user-guide/examples/standard_model.md)
-    * [Deploy PyFunc Model](user-guide/examples/pyfunc_model.md)
-    * [Run Batch Prediction Job](user-guide/examples/batch_prediction.md)
-    * [Using Transformers](user-guide/examples/transformer.md)
-    * [Others](user-guide/examples/others.md)
+* [Basic Concepts](user/basics.md)
+    * [Create a Model](user/model.md)
+    * [Create a Model Version](user/model_version.md)
+    * [Model Version Endpoint](user/model_version_endpoint.md)
+    * [Model Endpoint](user/model_endpoint.md)
+    * [Model Deployment and Serving](user/model_deployment_serving.md)
+    * [Delete a Model](user/model_deletion.md)
+    * [Delete a Model Version](user/model_version_deletion.md)
+* [Batch Prediction](user/batch_prediction.md)
+* [Transformer](user/transformer.md)
+    * [Standard Transformer](user/standard_transformer.md)
+        * [Standard Transformer Expression](user/transformer_expressions.md)
+        * [Standard Transformer for UPI](user/standard_transformer_upi.md)
+    * [Custom Transformer](user/custom_transformer.md)
+* [Examples](user/examples/README.md)
+    * [Deploy Standard Models](user/examples/standard_model.md)
+    * [Deploy PyFunc Model](user/examples/pyfunc_model.md)
+    * [Run Batch Prediction Job](user/examples/batch_prediction.md)
+    * [Using Transformers](user/examples/transformer.md)
+    * [Others](user/examples/others.md)
 
 ## Developer Guides
 
-* [Deploying Merlin](dev-guide/deploying-merlin/README.md)
-    * [Local Development](dev-guide/deploying-merlin/local_development.md)
-* [Architecture Overview](dev-guide/architecture.md)
+* [Deploying Merlin](developer/deploying-merlin/README.md)
+    * [Local Development](developer/deploying-merlin/local_development.md)
+* [Architecture Overview](developer/architecture.md)
 
 ## Reference
 

diff --git a/docs/dev-guide/architecture.md → docs/developer/architecture.md b/docs/dev-guide/architecture.md → docs/developer/architecture.md
@@ -36,9 +36,9 @@ The big advantage of a golang-migrate is that it can read migration files from t
 
 ### Merlin SDK
 
-[Merlin SDK](./../connecting-to-merlin/python-sdk.md) is a python library for interacting with Merlin. Data scientist can install merlin-sdk from Pypi and import it into their Python project or Jupyter notebook. It provides all the functionalites that users are allowed to perform in Merlin. Models can only be logged via the SDK.
+[Merlin SDK](./../user/connecting-to-merlin/python-sdk.md) is a python library for interacting with Merlin. Data scientist can install merlin-sdk from Pypi and import it into their Python project or Jupyter notebook. It provides all the functionalites that users are allowed to perform in Merlin. Models can only be logged via the SDK.
 
-Upon installing the sdk, you will also have access to the [Merlin CLI](./../connecting-to-merlin/merlin-cli.md)
+Upon installing the sdk, you will also have access to the [Merlin CLI](./../user/connecting-to-merlin/merlin-cli.md)
 
 ### CaraML MLP
 

diff --git a/docs/dev-guide/deploying-merlin/README.md → docs/developer/deploying-merlin/README.md b/docs/dev-guide/deploying-merlin/README.md → docs/developer/deploying-merlin/README.md
diff --git a/...ide/deploying-merlin/local_development.md → ...per/deploying-merlin/local_development.md b/...ide/deploying-merlin/local_development.md → ...per/deploying-merlin/local_development.md
diff --git a/docs/reference/e2e-test.md → docs/developer/e2e-test.md b/docs/reference/e2e-test.md → docs/developer/e2e-test.md
diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md
diff --git a/docs/maintainer/.gitkeep b/docs/maintainer/.gitkeep
diff --git a/docs/user-guide/autoscaling_policy.md → docs/user/autoscaling_policy.md b/docs/user-guide/autoscaling_policy.md → docs/user/autoscaling_policy.md
diff --git a/docs/user-guide/basics.md → docs/user/basics.md b/docs/user-guide/basics.md → docs/user/basics.md
diff --git a/docs/user-guide/batch_prediction.md → docs/user/batch_prediction.md b/docs/user-guide/batch_prediction.md → docs/user/batch_prediction.md
diff --git a/...-guide/configure_standard_transformer.gif → docs/user/configure_standard_transformer.gif b/...-guide/configure_standard_transformer.gif → docs/user/configure_standard_transformer.gif
diff --git a/docs/connecting-to-merlin/README.md → docs/user/connecting-to-merlin/README.md b/docs/connecting-to-merlin/README.md → docs/user/connecting-to-merlin/README.md
diff --git a/docs/connecting-to-merlin/merlin-cli.md → docs/user/connecting-to-merlin/merlin-cli.md b/docs/connecting-to-merlin/merlin-cli.md → docs/user/connecting-to-merlin/merlin-cli.md
diff --git a/docs/connecting-to-merlin/python-sdk.md → docs/user/connecting-to-merlin/python-sdk.md b/docs/connecting-to-merlin/python-sdk.md → docs/user/connecting-to-merlin/python-sdk.md
diff --git a/docs/user-guide/custom_model.md → docs/user/custom_model.md b/docs/user-guide/custom_model.md → docs/user/custom_model.md
diff --git a/docs/user-guide/custom_transformer.md → docs/user/custom_transformer.md b/docs/user-guide/custom_transformer.md → docs/user/custom_transformer.md
diff --git a/docs/user-guide/deployment_mode.md → docs/user/deployment_mode.md b/docs/user-guide/deployment_mode.md → docs/user/deployment_mode.md
diff --git a/docs/user-guide/examples/README.md → docs/user/examples/README.md b/docs/user-guide/examples/README.md → docs/user/examples/README.md
diff --git a/docs/user-guide/examples/batch_prediction.md → docs/user/examples/batch_prediction.md b/docs/user-guide/examples/batch_prediction.md → docs/user/examples/batch_prediction.md
diff --git a/docs/user-guide/examples/others.md → docs/user/examples/others.md b/docs/user-guide/examples/others.md → docs/user/examples/others.md
diff --git a/docs/user-guide/examples/pyfunc_model.md → docs/user/examples/pyfunc_model.md b/docs/user-guide/examples/pyfunc_model.md → docs/user/examples/pyfunc_model.md
diff --git a/docs/user-guide/examples/standard_model.md → docs/user/examples/standard_model.md b/docs/user-guide/examples/standard_model.md → docs/user/examples/standard_model.md
diff --git a/docs/user-guide/examples/transformer.md → docs/user/examples/transformer.md b/docs/user-guide/examples/transformer.md → docs/user/examples/transformer.md
diff --git a/docs/reference/limitations.md → docs/user/limitations.md b/docs/reference/limitations.md → docs/user/limitations.md
diff --git a/docs/user-guide/model.md → docs/user/model.md b/docs/user-guide/model.md → docs/user/model.md
diff --git a/docs/user-guide/model_deletion.md → docs/user/model_deletion.md b/docs/user-guide/model_deletion.md → docs/user/model_deletion.md
diff --git a/docs/user-guide/model_deployment_serving.md → docs/user/model_deployment_serving.md b/docs/user-guide/model_deployment_serving.md → docs/user/model_deployment_serving.md
diff --git a/docs/user-guide/model_endpoint.md → docs/user/model_endpoint.md b/docs/user-guide/model_endpoint.md → docs/user/model_endpoint.md
diff --git a/docs/user-guide/model_version.md → docs/user/model_version.md b/docs/user-guide/model_version.md → docs/user/model_version.md
diff --git a/docs/user-guide/model_version_deletion.md → docs/user/model_version_deletion.md b/docs/user-guide/model_version_deletion.md → docs/user/model_version_deletion.md
diff --git a/docs/user-guide/model_version_endpoint.md → docs/user/model_version_endpoint.md b/docs/user-guide/model_version_endpoint.md → docs/user/model_version_endpoint.md
diff --git a/docs/user-guide/standard_transformer.md → docs/user/standard_transformer.md b/docs/user-guide/standard_transformer.md → docs/user/standard_transformer.md
diff --git a/docs/user-guide/standard_transformer_upi.md → docs/user/standard_transformer_upi.md b/docs/user-guide/standard_transformer_upi.md → docs/user/standard_transformer_upi.md
diff --git a/docs/user-guide/transformer.md → docs/user/transformer.md b/docs/user-guide/transformer.md → docs/user/transformer.md
diff --git a/docs/user-guide/transformer_expressions.md → docs/user/transformer_expressions.md b/docs/user-guide/transformer_expressions.md → docs/user/transformer_expressions.md