Skip to content

Commit

Permalink
[workflow] Add a workflow to enforce PR title format (#1219)
Browse files Browse the repository at this point in the history
* [skip ci] [workflow] Add a workflow to enforce PR title format

* [skip ci] fix yml syntax

* [skip ci] fix typo

* [skip ci] enforce code format

* [skip ci] trig

* [skip ci] bad

* [skip ci] bad2

* [skip ci] good

* [skip ci] Update contributor_guide

* [skip ci] enforce code format

* [skip ci] no duplicate uppercase tag like #1189

* [skip ci] Apply suggestions from code review

Co-authored-by: Ye Kuang <k-ye@users.noreply.github.com>

* [skip ci]

* [skip ci] enforce code format

* [skip ci] Apply suggestions from code review

Co-authored-by: Chengchen(Rex) Wang <14366016+rexwangcc@users.noreply.github.com>

* [skip ci] apply (json & exit)

* [skip ci] enforce code format

* [skip ci] Update .github/pull_request_template.md

Co-authored-by: Chengchen(Rex) Wang <14366016+rexwangcc@users.noreply.github.com>

* [skip ci] No colorama :(

* [skip ci] enforce code format

* [skip ci] Update docs/contributor_guide.rst

Co-authored-by: Ye Kuang <k-ye@users.noreply.github.com>

Co-authored-by: Taichi Gardener <taichigardener@gmail.com>
Co-authored-by: Ye Kuang <k-ye@users.noreply.github.com>
Co-authored-by: Chengchen(Rex) Wang <14366016+rexwangcc@users.noreply.github.com>
  • Loading branch information
4 people authored Jun 13, 2020
1 parent 434c5fa commit c61c2c4
Show file tree
Hide file tree
Showing 8 changed files with 198 additions and 60 deletions.
25 changes: 20 additions & 5 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -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/)

----
18 changes: 15 additions & 3 deletions .github/workflows/persubmit.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 }}
11 changes: 11 additions & 0 deletions .tmp_idle_source
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@

=====
@ti.kernel
def func(): pass


=====
func()

=====
func()
33 changes: 14 additions & 19 deletions docs/contributor_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand All @@ -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
---------------------------------------
Expand Down
46 changes: 46 additions & 0 deletions misc/check_pr_title.py
Original file line number Diff line number Diff line change
@@ -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!')
48 changes: 48 additions & 0 deletions misc/count_tags.py
Original file line number Diff line number Diff line change
@@ -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')
31 changes: 31 additions & 0 deletions misc/prtags.json
Original file line number Diff line number Diff line change
@@ -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"
}
46 changes: 13 additions & 33 deletions python/taichi/make_changelog.py
Original file line number Diff line number Diff line change
@@ -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))
Expand All @@ -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)
Expand Down

0 comments on commit c61c2c4

Please sign in to comment.