Source Code Format Checks (#380)

This change includes some tools to keep a consistent format of the repository's source files, including:

- a `Checks` workflow which errors if any of a branch's changed files require formatting.   We can extend this workflow with copyright header checks in the future and the pre-existing `Check PR Labels` has been folded into it.
- updates to `install_prereqs_desktop.py` to ensure that clang-format is installed.
- updates to `scripts/format_code.py` to reduce logging in non-verbose mode.
- a pre-commit githook. Note that the githook has to be installed manually by copying it from `scripts/git/hooks/pre-commit` to `.git/hooks/pre-commit`
- an update to our Contribution guidelines with formatting instructions.

Author: DellaBitta

.github/workflows/check-labels.yml

@@ -0,0 +1,44 @@
+name: Checks
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, labeled, unlabeled]
+
+env:
+  triggerLabelFull: "tests-requested: full"
+  triggerLabelQuick: "tests-requested: quick"
+  statusLabelInProgress: "tests: in-progress"
+  statusLabelFailed: "tests: failed"
+
+jobs:
+  check_integration_test_labels:
+    # This check fails if integration tests are queued, in progress, or failed.
+    runs-on: ubuntu-latest
+    steps:
+    - uses: docker://agilepathway/pull-request-label-checker:latest
+      with:
+        none_of: "${{ env.statusLabelInProgress }},${{ env.statusLabelFailed }},${{ env.triggerLabelFull }},${{ env.triggerLabelQuick }}"
+        repo_token: ${{ github.token }}
+  file_format_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: false
+      - name: Setup python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Install prerequisites
+        run: python scripts/gha/install_prereqs_desktop.py
+      - name: log clang format version
+        shell: bash
+        run: clang-format --version
+      - name: git fetch origin main
+        shell: bash
+        run: git fetch origin main
+      - name: Detect Formatting Changes
+        shell: bash
+        run: python3 scripts/format_code.py -git_diff -noformat_file -verbose
+
+

.github/workflows/checks.yml

@@ -118,6 +118,11 @@ Before you submit your pull request consider the following guidelines:
 * Follow our [Coding Rules](#rules).
 * Avoid checking in files that shouldn't be tracked (e.g `.tmp`, `.idea`).
   We recommend using a [global](#global-gitignore) gitignore for this.
+* Format your code:
+     ```shell
+     python3 scripts/format_code.py -git_diff -verbose
+     ```
+
 * Commit your changes using a descriptive commit message.
 
      ```shell

CONTRIBUTING.md

@@ -39,20 +39,20 @@
 # Flag Definitions:
 FLAGS = flags.FLAGS
 
-flags.DEFINE_boolean("git_diff", False, "Use git-diff to assemble a file list")
-flags.DEFINE_string("git_range", "origin/main..", "the range string when using "
-  "git-diff.")
-flags.DEFINE_multi_string("f", None, "Append the filename to the list of "
-  "files to check.")
-flags.DEFINE_multi_string("d", None, 
-  "Append the directory to the file list to format.")
-flags.DEFINE_boolean("r", False, 
+flags.DEFINE_boolean('git_diff', False, 'Use git-diff to assemble a file list')
+flags.DEFINE_string('git_range', 'origin/main..', 'the range string when using '
+  'git-diff.')
+flags.DEFINE_multi_string('f', None, 'Append the filename to the list of '
+  'files to check.')
+flags.DEFINE_multi_string('d', None,
+  'Append the directory to the file list to format.')
+flags.DEFINE_boolean('r', False,
   "Recurse through the directory's children When formatting a target directory.")
-flags.DEFINE_boolean("format_file", True, "Format files in place.")
-flags.DEFINE_boolean("verbose", False, "Execute in verbose mode.")
+flags.DEFINE_boolean('format_file', True, 'Format files in place.')
+flags.DEFINE_boolean("verbose", False, 'Execute in verbose mode.')
 
 # Constants:
-FILE_TYPE_EXTENSIONS = (".cpp", ".cc", ".c", ".h")
+FILE_TYPE_EXTENSIONS = ('.cpp', '.cc', '.c', '.h')
 """Tuple: The file types to run clang-format on.
 Used to filter out results when searching across directories or git diffs.
 """
@@ -73,7 +73,7 @@ def does_file_need_formatting(filename):
   for line in result.stdout.decode('utf-8').splitlines():
     if line.strip().startswith("<replacement "):
       return True
-  return False    
+  return False
 
 def format_file(filename):
   """Executes clang-format on the file to reformat it according to our
@@ -187,10 +187,14 @@ def is_file_objc_header(filename):
     bool: True if the header file contains known obj-c language definitions.
     Returns False otherwise.
   """
-  if '.h' not in filename:
-    return False
-  objective_c_tags = [ '@end', '@class', '#import']
-  for line in open(filename):
+  _, ext = os.path.splitext(filename)
+  if ext != '.h':
+   return False  
+  objective_c_tags = ('@end', '@class', '#import')
+  
+  with open(filename) as header_file:
+   lines = header_file.readlines()
+   for line in lines:
     for tag in objective_c_tags:
       if tag in line:
         return True
@@ -211,8 +215,8 @@ def main(argv):
     filenames += git_diff_list_files()
 
   exit_code = 0
-  if 0 == len(filenames):
-    print("No files to format.")
+  if not filenames:
+    print('No files to format.')
     sys.exit(exit_code)
 
   if FLAGS.verbose:
@@ -224,7 +228,7 @@ def main(argv):
         if does_file_need_formatting(filename):
           if is_file_objc_header(filename):
             if FLAGS.verbose:
-              print('  - Ignoring obj header: "{0}"'.format(filename)) 
+              print('  - IGNORE OBJC: "{0}"'.format(filename)) 
           else:
             if FLAGS.verbose:
               print('  - FRMT: "{0}"'.format(filename))

scripts/format_code.py

@@ -64,10 +64,18 @@ def main():
     if utils.is_linux_os():
         # sudo apt install ccache
         utils.run_command(['apt', 'install', '-y', 'ccache'], as_root=True)
-
     elif utils.is_mac_os():
         # brew install ccache
         utils.run_command(['brew', 'install', 'ccache'])
+  
+  # Install clang-format on linux/mac if its not installed already
+  if not utils.is_command_installed('clang-format'):
+    if utils.is_linux_os():
+        # sudo apt install clang-format
+        utils.run_command(['apt', 'install', '-y','clang-format'], as_root=True)
+    elif utils.is_mac_os():
+        # brew install protobuf
+        utils.run_command(['brew', 'install', 'clang-format'])
 
   # Install required python dependencies. 
   # On Catalina, python2 in installed as default python.

scripts/gha/install_prereqs_desktop.py

@@ -0,0 +1,2 @@
+echo .git/hooks/presubmit Checking File Formats
+python3 scripts/format_code.py -git_diff -noformat_file