[workflow] Add a workflow to enforce PR title format

.github/pull_request_template.md

@@ -1,8 +1,23 @@
-<!-- Thank for your PR! If it's your first time contributing to Taichi, please make sure you have read Contributor Guideline(https://taichi.readthedocs.io/en/latest/contributor_guide.html) (last update: March 26, 2019). -->
+<!--
+Thanks for your PR!
+If it's your first time contributing to Taichi, please make sure you have read our Contributor Guideline:
+  https://taichi.readthedocs.io/en/latest/contributor_guide.html
 
-<!-- Please always prepend your PR title with tags such as [Metal], [CUDA], [Doc], [Example]. Use a lowercased tag (e.g. [cuda]), for PRs that are invisible to end-users (e.g. intermediate implementation). More details: http://taichi.readthedocs.io/en/latest/contributor_guide.html#prtags -->
+- Please always prepend your PR title with tags such as [CUDA], [Lang], [Doc], [Example], e.g.:
+    [Lang] Add ti.Complex as Taichi class
+- Use a lowercased tag for PRs that are invisible to end-users, i.e., won't be highlighted in changelog:
+    [cuda] [test] Fix out-of-memory error while running test
+- More details: http://taichi.readthedocs.io/en/latest/contributor_guide.html#prtags
 
-Related issue = #... (if any)
+- Please fill the following blank with the issue number this PR related to (if any):
+    Related issue = #2345
+- If your PR will fix the issue **completely**, use the `close` or `fixes` keyword:
+    Related issue = close #2345
+- So that when the PR gets merged, GitHub will **automatically** close the issue #2345 for you :)
+- If the PR doesn't belong to any existing issue, and this is a trivial change, feel free to leave it blank :)
+  -->
+Related issue = #
 
-- [[Click here for the format server]](http://kun.csail.mit.edu:31415/)
-- [[Click here for coverage report]](http://codecov.io/gh/taichi-dev/taichi/)
+[[Click here for the format server]](http://kun.csail.mit.edu:31415/)
+
+----

.github/workflows/persubmit.yml

@@ -11,9 +11,6 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python: [3.6, 3.7, 3.8]
-        include:
-          - os: ubuntu-16.04
-            python: 3.7
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2
@@ -72,3 +69,18 @@ jobs:
           git commit -m "enforce code format" || true
           # exit with 1 if there were differences:
           git diff _last_squash _enforced_format --exit-code
+
+  title_format:
+    name: Check PR Title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+
+      - name: Run PR Title Checker
+        run: |
+          python misc/check_pr_title.py "$PR_TITLE"
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}

.tmp_idle_source

@@ -0,0 +1,11 @@
+
+=====
+@ti.kernel
+def func(): pass
+
+
+=====
+func()
+
+=====
+func()

docs/contributor_guide.rst

@@ -129,48 +129,42 @@ PR title format and tags
 ------------------------
 PR titles will be part of the commit history reflected in the ``master`` branch, therefore it is important to keep PR titles readable.
 
- - The first letter of the PR title body should be capitalized, unless the title starts with an identifier:
+ - Please always prepend **at least one tag** such as ``[Lang]`` to PR titles:
 
-     - E.g., "[doc] improve documentation" should be formatted as "[doc] Improve documentation";
-     - "[Lang] ti.sqr(x) is now deprecated" is fine because ``ti`` is an identifier.
+     - When using multiple tags, make sure there is exactly one space between tags;
+     - E.g., "[Lang][refactor]" (no space) should be replaced by "[Lang] [refactor]";
 
- - Please do not include back quotes ("`") in PR titles.
- - Please always prepend at least one tag such as ``[Metal]`` to PR titles:
+ - The first letter of the PR title body should be capitalized:
 
-     - When using multiple tags, make sure there is exactly one space between tags;
-     - E.g., "[Metal][refactor]" (no space) should be formatted as "[Metal] [refactor]";
+     - E.g., ``[Doc] improve documentation`` should be replaced by ``[Doc] Improve documentation``;
+     - ``[Lang] "ti.sqr(x)" is now deprecated`` is fine because ``"`` is a symbol.
+
+ - Please do not include back quotes ("`") in PR titles.
 
  - For example, "[Metal] Support bitmasked SNode", "[OpenGL] AtomicMin/Max support", or "[Opt] [IR] Enhanced constant folding".
 
-Existing tags:
+Frequently used tags:
 
-- ``[Metal], [OpenGL], [CPU], [CUDA], [AMDGPU], [LLVM]``: backends;
+- ``[Metal], [OpenGL], [CPU], [CUDA], [LLVM]``: backends;
 - ``[LLVM]``: the LLVM backend shared by CPUs and CUDA;
 - ``[Lang]``: frontend language features, including syntax sugars;
 - ``[Std]``: standard library, e.g. ``ti.Matrix`` and ``ti.Vector``;
 - ``[IR]``: intermediate representation;
-- ``[Sparse]``: sparse computation, dynamic memory allocator, and garbage collection;
 - ``[Opt]``: IR optimization passes;
-- ``[Async]``: asynchronous execution engine;
-- ``[Type]``: type system;
-- ``[Infra]``: general infrastructure, e.g. logging, image reader;
 - ``[GUI]``: the built-in GUI system;
 - ``[Refactor]``: code refactoring;
-- ``[AutoDiff]``: automatic differentiation;
 - ``[CLI]``: commandline interfaces, e.g. the ``ti`` command;
 - ``[Doc]``: documentation under ``docs/``;
 - ``[Example]``: examples under ``examples/``;
 - ``[Test]``: adding or improving tests under ``tests/``;
-- ``[Benchmark]``: Benchmarking & regression tests;
 - ``[Linux]``: Linux platform;
 - ``[Mac]``: Mac OS X platform;
 - ``[Windows]``: Windows platform;
-- ``[PyPI]``: PyPI package release;
-- ``[Workflow]``: GitHub Actions/Workflows;
 - ``[Perf]``: performance improvements;
 - ``[Misc]``: something that doesn't belong to any category, such as version bump, reformatting;
 - ``[Bug]``: bug fixes;
-- **When introducing a new tag, please update the list here in the first PR with that tag, so that people can follow.**
+- Check out more tags in `misc/prtags.json <https://github.com/taichi-dev/taichi/blob/master/misc/prtags.json>`_.
+- When introducing a new tag, please update the list in ``misc/prtags.json`` in the first PR with that tag, so that people can follow.
 
 .. note::
 
@@ -179,8 +173,9 @@ Existing tags:
   This is done by **capitalizing PR tags**:
 
    - PRs with visible/notable features to the users should be marked with tags starting with **the first letter capitalized**, e.g. ``[Metal], [OpenGL], [IR], [Lang], [CLI]``.
-     When releasing a new version, a script will generate a changelog with these changes (PR title) highlighted. Therefore it is **important** to make sure the end-users can understand what your PR does, **based on your PR title**.
+     When releasing a new version, a script (``python/taichi/make_changelog.py``) will generate a changelog with these changes (PR title) highlighted. Therefore it is **important** to make sure the end-users can understand what your PR does, **based on your PR title**.
    - Other PRs (underlying development/intermediate implementation) should use tags with **everything in lowercase letters**: e.g. ``[metal], [opengl], [ir], [lang], [cli]``.
+   - Because of the way the release changelog is generated, there should be **at most one captialized tag** in a PR title to prevent duplicate PR highlights. For example, ``[GUI] [Mac] Support modifier keys`` (#1189) is a bad example, we should use ``[gui] [Mac] Support modifier keys in GUI`` instead. Please capitalize the tag that is most relevant to the PR.
 
 Tips on the Taichi compiler development
 ---------------------------------------

misc/check_pr_title.py

@@ -0,0 +1,46 @@
+import sys, os, json
+
+title = sys.argv[1]
+print(f'Checking PR title: {title}')
+
+this_dir = os.path.dirname(os.path.abspath(__file__))
+json_path = os.path.join(this_dir, 'prtags.json')
+with open(json_path) as f:
+    prtags = json.load(f)
+
+if not title.startswith('['):
+    exit(f'PR title does not start with any tag: {title}')
+
+if title.endswith(' '):
+    exit(f'PR title should not end with a space: {title}')
+
+if title.endswith(']'):
+    exit(f'PR title should have bodies regardless tags: {title}')
+
+if '`' in title:
+    exit(f'PR title should not contain backquotes (`): {title}')
+
+for x in title.split(']')[1:]:
+    if x[0] != ' ':
+        exit(f'No space before: {x}')
+    if x[1] == ' ':
+        exit(f'Extra space before: {x[2:]}')
+
+x = title.split(']')[-1].strip()
+if x[0].islower():
+    exit(f'PR title should be uppercase at: {x}')
+
+had_upper = False
+for x in title.split('] ')[:-1]:
+    if x[0] != '[':
+        exit(f'No starting [ for tag: {x}]')
+    if x[1:].lower() not in prtags.keys():
+        exit(f'Unrecognized PR tag: [{x[1:]}]')
+    # 'Misc'.islower() -> False, 'Misc'.isupper() -> False
+    # 'misc'.islower() -> True, 'misc'.isupper() -> False
+    if not x[1:].islower():
+        if had_upper:
+            exit(f'At most 1 uppercase tag expected, got: [{x[1:]}]')
+        had_upper = True
+
+print('OK!')

misc/count_tags.py

@@ -0,0 +1,48 @@
+import sys, os
+from git import Repo
+
+commits = list(Repo('.').iter_commits('master'))
+
+authors = {}
+notable = {}
+changelog = {}
+
+for i, c in enumerate(commits):
+    s = c.summary
+
+    tags = []
+    while s[0] == '[':
+        r = s.find(']')
+        tag = s[1:r]
+        tags.append(tag)
+        s = s[r + 1:]
+        s = s.strip()
+
+    for tag in tags:
+        if tag[0].isupper():
+            tag = tag.lower()
+            notable[tag] = notable.get(tag, 0) + 1
+        changelog[tag] = changelog.get(tag, 0) + 1
+
+    a = str(c.author).split(' <')[0]
+    authors[a] = authors.get(a, 0) + 1
+
+
+def print_table(tab, name=''):
+    print('')
+    print(f' | {name} | counts |')
+    print(' | :--- | ---: |')
+    tab = sorted(tab.items(), key=lambda x: x[1], reverse=True)
+    for a, n in tab:
+        print(f' | {a} | {n} |')
+    return tab
+
+
+print('Authors:')
+print_table(authors, 'author')
+print('')
+print('Highlights:')
+print_table(notable, 'tag')
+print('')
+print('Full changelog:')
+print_table(changelog, 'tag')

misc/prtags.json

@@ -0,0 +1,31 @@
+{
+  "cpu"             : "CPU backends",
+  "cuda"            : "CUDA backend",
+  "doc"             : "Documentation",
+  "infra"           : "Infrastructure",
+  "cli"             : "Command line interface",
+  "ir"              : "Intermediate representation",
+  "lang"            : "Language and syntax",
+  "metal"           : "Metal backend",
+  "opengl"          : "OpenGL backend",
+  "misc"            : "Miscellaneous",
+  "std"             : "Standard library",
+  "opt"             : "IR optimization passes",
+  "example"         : "Examples",
+  "pypi"            : "PyPI package",
+  "autodiff"        : "Automatic differentiation",
+  "sparse"          : "Sparse computation",
+  "gui"             : "GUI",
+  "llvm"            : "LLVM backend (CPU and CUDA)",
+  "refactor"        : "Refactor",
+  "bug"             : "Bug fixes",
+  "test"            : "Tests",
+  "benchmark"       : "Benchmarking",
+  "async"           : "AsyncEngine",
+  "workflow"        : "GitHub Actions/Workflows",
+  "linux"           : "Linux",
+  "mac"             : "Mac OS X",
+  "windows"         : "Windows",
+  "perf"            : "Performance improvements",
+  "release"         : "Release"
+}

python/taichi/make_changelog.py

@@ -1,9 +1,19 @@
-# Usage: python3 misc/make_changelog.py [v0.x.y]
+# Usage: make_changelog.py [v0.x.y]
 
-import sys
+import sys, os, json
 from git import Repo
 
 
+def load_pr_tags():
+    this_dir = os.path.dirname(os.path.abspath(__file__))
+    json_path = os.path.join(this_dir, '../../misc/prtags.json')
+    details = {}
+    with open(json_path) as f:
+        details = json.load(f)
+    details['release'] = ''
+    return details
+
+
 def main(ver='master', repo_dir='.'):
     g = Repo(repo_dir)
     commits = list(g.iter_commits(ver, max_count=200))
@@ -15,37 +25,7 @@ def format(c):
     notable_changes = {}
     all_changes = []
 
-    details = {
-        'cpu': 'CPU backends',
-        'cuda': 'CUDA backend',
-        'doc': 'Documentation',
-        'infra': 'Infrastructure',
-        'cli': 'Command line interface',
-        'ir': 'Intermediate representation',
-        'lang': 'Language and syntax',
-        'metal': 'Metal backend',
-        'opengl': 'OpenGL backend',
-        'misc': 'Miscellaneous',
-        'std': 'Standard library',
-        'opt': 'IR optimization passes',
-        'example': 'Examples',
-        'pypi': 'PyPI package',
-        'autodiff': 'Automatic differentiation',
-        'sparse': 'Sparse computation',
-        'gui': 'GUI',
-        'llvm': 'LLVM backend (CPU and CUDA)',
-        'refactor': 'Refactor',
-        'bug': 'Bug fixes',
-        'test': 'Tests',
-        'benchmark': 'Benchmarking',
-        'async': 'AsyncEngine',
-        'workflow': 'GitHub Actions/Workflows',
-        'linux': 'Linux',
-        'mac': 'Mac OS X',
-        'windows': 'Windows',
-        'perf': 'Performance improvements',
-        'release': '',
-    }
+    details = load_pr_tags()
 
     for i, c in enumerate(commits):
         s = format(c)