Merge pull request #607 from veselypeta/petr/add-exp-feature-template

[UR] Add script to generate experimental feature template files

Author: veselypeta

scripts/add_experimental_feature.py

@@ -0,0 +1,80 @@
+"""
+ Copyright (C) 2023 Intel Corporation
+
+ Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ See LICENSE.TXT
+ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+"""
+import argparse
+import sys
+from util import makoWrite
+import re
+import subprocess
+
+def verify_kebab_case(input: str) -> bool:
+    # kebab case regex from https://github.com/expandjs/expandjs/blob/master/lib/kebabCaseRegex.js
+    kebab_case_re = r"^([a-z](?![\d])|[\d](?![a-z]))+(-?([a-z](?![\d])|[\d](?![a-z])))*$|^$"
+    pattern = re.compile(kebab_case_re)
+    if pattern.match(input) is None:
+        return False
+    return True
+
+
+def get_user_name_email_from_git_config():
+    proc = subprocess.run(["git", "config", "user.name"], stdout=subprocess.PIPE)
+    if proc.returncode != 0:
+        raise Exception("Failed to get user name from git config.")
+    user_name = proc.stdout.decode().strip()
+
+    proc = subprocess.run(["git", "config", "user.email"], stdout=subprocess.PIPE)
+    if proc.returncode != 0:
+        raise Exception("Failed to get user email from git config.")
+    user_email = proc.stdout.decode().strip()
+
+    return user_name, user_email
+
+
+def main():
+
+    argParser = argparse.ArgumentParser()
+    argParser.add_argument("name", help="must be lowercase and kebab case i.e. command-buffer", type=str)
+    argParser.add_argument("--dry_run", help="run the script without generating any files", action='store_true')
+    args = argParser.parse_args()
+
+    if not verify_kebab_case(args.name):
+        print("Name must be lowercase and kebab-case i.e. command-buffer.")
+        sys.exit(1)
+
+    user_name, user_email = get_user_name_email_from_git_config()
+    user = {'email':user_email, 'name': user_name}
+
+    exp_feat_name = args.name
+    
+    out_yml_name = f"exp-{exp_feat_name}.yml"
+    out_rst_name = f"EXP-{exp_feat_name.upper()}.rst"
+
+    yaml_template_path = "./scripts/templates/exp_feat.yml.mako"
+    rst_template_path = "./scripts/templates/exp_feat.rst.mako"
+    out_yml_path = f"./scripts/core/{out_yml_name}"
+    out_rst_path = f"./scripts/core/{out_rst_name}"
+
+    if not args.dry_run:
+        makoWrite(yaml_template_path, out_yml_path, name=exp_feat_name)
+        makoWrite(rst_template_path, out_rst_path, name=exp_feat_name, user=user)
+
+
+    print(f"""\
+Successfully generated the template files needed for {exp_feat_name}.
+
+You can now implement your feature in the following files:
+    * {out_yml_name} 
+    * {out_rst_name}
+""")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        exit(130)

scripts/core/CONTRIB.rst

@@ -207,6 +207,15 @@ Experimental features *must* be defined in two new files, where
 *   ``scripts/core/exp-<feature>.yml`` defines the interface as an input to
     `Generating Source`_.
 
+To simplify this process please use the provided python script which will create
+these template files for you. You can then freely modify these files to 
+implement your experimental feature. 
+
+.. code-block:: console
+
+    $ python scripts/add_experimental_feature.py <name-of-your-experimental-feature>
+
+
 Naming Convention
 -----------------
 

scripts/templates/exp_feat.rst.mako

@@ -0,0 +1,79 @@
+<%text><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+</%text>
+.. _experimental-${name}:
+
+================================================================================
+${" ".join(name.split("-")).title()}
+================================================================================
+
+.. warning::
+
+    Experimental features:
+
+    *   May be replaced, updated, or removed at any time.
+    *   Do not require maintaining API/ABI stability of their own additions over
+        time.
+    *   Do not require conformance testing of their own additions.
+
+
+Terminology
+--------------------------------------------------------------------------------
+.. comment:
+    If your experimental feature introduces a new concept or terminology. Please 
+    provide a detailed explanation in this section. If this does not apply to 
+    your feature you may freely delete this section.
+
+Motivation
+--------------------------------------------------------------------------------
+.. comment:
+    In this section you *must* justify your motivation for adding this 
+    experimental feature. You should also state at least one adapter upon which 
+    this feature can be supported.
+
+API
+--------------------------------------------------------------------------------
+.. comment:
+    In this section you *must* list all additions your experimental feature will 
+    make to the Unified Runtime specification. If your experimental feature does 
+    not include additions from one or more of the sections listed below, you may 
+    freely remove them.
+
+Macros
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* <%text>${x}</%text>_EXP_MACRO
+
+Enums
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* <%text>${x}</%text>_exp_enum_t
+
+Structs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* <%text>${x}</%text>_exp_struct_t 
+
+Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* <%text>${x}</%text>FunctionExp
+
+Changelog
+--------------------------------------------------------------------------------
+.. comment:
+    When making a change to an experimental feature, increment the version and 
+    provide a brief description of the change in the table below.
+
++-----------+------------------------+
+| Revision  | Changes                |
++===========+========================+
+| 1.0       | Intial Draft           |
++-----------+------------------------+
+
+Contributors
+--------------------------------------------------------------------------------
+.. comment:
+    Please list all people who wish to be credited for contribution to this 
+    experimental feature.
+
+* ${user['name']} `${user['email']} <${user['email']}>`_

scripts/templates/exp_feat.yml.mako

@@ -0,0 +1,19 @@
+<%
+import re
+from templates import helper as th
+import datetime
+%><%
+    year_now=datetime.date.today().year
+%>#
+# Copyright (C) ${year_now} Intel Corporation
+#
+# Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+# See LICENSE.TXT
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# See YaML.md for syntax definition
+#
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Unified Runtime Experimental APIs for ${" ".join(name.split("-")).title()}"
+ordinal: "99"