ci: add conventional checks for PR title and docs (#3054)

With this PR merged, new checks are introduced:

the PR titles should follow the [Conventional Commits
specification](https://www.conventionalcommits.org/en/v1.0.0/), which in
the format of <type>(<scope>): <description>. e.g.,
- fix: Correct typo
- feat(interactive): Add support for g.V().outE().inV()
- refactor!: Drop support for Python 3.8
- feat(analytical): Add delta-version for PageRank

if the PR is in type of `feat(<scope>):`, then documentation must be
updated.

Author: yecol

.github/workflows/pr-check.yml

@@ -0,0 +1,84 @@
+name: PR-Check
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  conventional-pr-check:
+    runs-on: ubuntu-20.04
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v3
+      with:
+        repository: ${{ github.event.pull_request.head.repo.full_name }}
+        ref: ${{ github.event.pull_request.head.ref }}
+        submodules: true
+        fetch-depth: 0
+
+    - uses: amannn/action-semantic-pull-request@v5
+      id: pr-convention
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+          # Types allowed (newline-delimited).
+          # Default: https://github.com/commitizen/conventional-commit-types
+          types: |
+            build
+            ci
+            docs
+            feat
+            fix
+            perf
+            refactor
+            test
+            chore
+          # Scopes allowed (newline-delimited).
+          scopes: |
+            core
+            python
+            k8s
+            coordinator
+            one
+            interactive
+            insight
+            analytical
+            learning
+          # A scope can be not provided.
+          requireScope: false
+          disallowScopes: |
+            release
+            [A-Z]+
+          # If the PR contains one of these newline-delimited labels, the
+          # validation is skipped.
+          ignoreLabels: |
+            bot
+            ignore-semantic-pull-request
+
+  feature-docs-check:
+    runs-on: ubuntu-20.04
+    needs: conventional-pr-check
+    steps:
+    - uses: dorny/paths-filter@v2
+      id: doc-changes
+      with:
+        filters: |
+          src:
+            - 'docs/**'
+
+    - uses: actions-ecosystem/action-regex-match@v2
+      id: pr-regex-match
+      with:
+        text: ${{ github.event.pull_request.title }}
+        regex: 'feat.*'
+
+    - if: ${{ steps.pr-regex-match.outputs.match != '' && steps.doc-changes.outputs.src == 'false' }}
+      run: |
+        # echo "title=${{ github.event.pull_request.title }}"
+        # echo "steps.pr-regex-match.outputs.match=${{ steps.pr-regex-match.outputs.match }}"
+        # echo "steps.doc-changes.outputs.src=${{ steps.doc-changes.outputs.src }}"
+        echo " ❌ Uh oh! ❌ \n
+             We suggest that a PR with type @feat should has corresponding documentations. \n
+             If you believe this PR could be merged without documentation, please add @yecol as an extra reviewer for confirmation."
+        exit 1

docs/development/how_to_contribute.md

@@ -109,7 +109,45 @@ Follow [our code style guide](./code_style_guide.md) to attain the proper code f
 
 ### Submitting Your Changes
 
-See [our guide on how to submit a pull request](./how_to_submit_pr.md).
+To submit your changes, you will need to open a pull request (PR) against the main repository. If you're new to GitHub, you can find instructions on how to do that in [GitHub's documentation](https://help.github.com/articles/creating-a-pull-request). GraphScope requires PR titles to follow a specific format (a.k.a., [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/)), depending on the type of change you're making. The format is as follows:
+
+**type(scope): brief desciption about the pr**
+
+Below are some examples of the valid PR titles:
+
+- fix: Correct typo
+- feat(interactive): Add support for g.V().outE().inV()
+- refactor!: Drop support for Python 3.8
+- feat(analytical): Add delta-version for PageRank
+
+````{note}
+Note that since pull request titles only have a single line, you have to use ! to indicate breaking changes.
+````
+
+The **type** must be one of the following:
+
+- build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+- ci: Changes to our CI configuration files and scripts
+- docs: Documentation only changes
+- feat: A new feature
+- fix: A bug fix
+- perf: A code change that improves performance
+- refactor: A code change that neither fixes a bug nor adds a feature
+- test: Adding missing tests or correcting existing tests
+- chore: A routine task of development
+
+The **scope** is optional. However, if it assigned, it must be one of the following:
+- core
+- python
+- k8s
+- coordinator
+- one
+- interactive
+- insight
+- analytical
+- learning
+
+In addtion to the conventional commit specification, we also require the PRs with feature update, (i.e., titled with feat:) should update the corresponding documentations. The repo depolyed a CI check to ensure this.
 
 ### Discussing and Keeping Your Pull Request Updated