style(tox): prepare for fixer scripts

The previous code assumes each tox script is a checker.
We want to add fixer scripts (not voting but editing) soon.

This is the less interesting part of the process,
renaming things and updating comments.

Includes some basic descriptions of how fixers differ from checkers.

Change-Id: I1ca1572a328acd02b41dcf4e70d7cb3746a03b03
Signed-off-by: Vratko Polak <vrpolak@cisco.com>

10 files changed, 38 insertions, 28 deletions

diff --git a/resources/libraries/bash/entry/check/README.txt b/resources/libraries/bash/entry/tox/README.txt
index 7f86d83b58..e13b60209e 100644
--- a/resources/libraries/bash/entry/check/README.txt
+++ b/resources/libraries/bash/entry/tox/README.txt
@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
@@ -11,10 +11,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-This directory contains checker scripts and other files they need.
-Each checker script is assumed to be run from tox,
+This directory contains tox scripts and other files they need.
+Generally, a tox script is either a checker (suitable for automated verify)
+or a fixer (manually started, risky as uncommitted edits can be lost).
+Each tox script is assumed to be run from tox,
 when working directory is set to ${CSIT_DIR}.
-Each script should:
+
+Each checker script should:
 + Return nonzero exit code when it fails.
 ++ The tox might ignore the code when the check is not blocking.
 + Write less verbose output to stderr.
@@ -25,3 +28,12 @@ Each script should:
 ++ The level of "less verbose" depends on check and state of codebase.
 + TODO: Should we carefully document which files are
   whitelisted/blacklisted for a particulat check?
+
+Each fixer script should:
++ Perform edits on current filesystem
++ Not assume git is clean (there may be uncommitted edits).
++ Use "git diff HEAD~" to get both comitted and uncomitted edits to analyze.
++ Output whatever it wants (possibly nothing).
+
+TODO: Should checkers be named differently than fixers?
+      E.g. both scripts and tox environments start with fix_?
diff --git a/resources/libraries/bash/entry/check/autogen.sh b/resources/libraries/bash/entry/tox/autogen.sh
index d7cd8e0dbd..40cc2c2066 100644
--- a/resources/libraries/bash/entry/check/autogen.sh
+++ b/resources/libraries/bash/entry/tox/autogen.sh
@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
diff --git a/resources/libraries/bash/entry/check/copyright_year.sh b/resources/libraries/bash/entry/tox/copyright_year.sh
index dae1a8dc46..9ed9fcb653 100644
--- a/resources/libraries/bash/entry/check/copyright_year.sh
+++ b/resources/libraries/bash/entry/tox/copyright_year.sh
@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
diff --git a/resources/libraries/bash/entry/check/doc_verify.sh b/resources/libraries/bash/entry/tox/doc_verify.sh
index baa9d8aa74..7eec4b69e4 100644
--- a/resources/libraries/bash/entry/check/doc_verify.sh
+++ b/resources/libraries/bash/entry/tox/doc_verify.sh
@@ -1,6 +1,4 @@
-#!/usr/bin/env bash
-
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
diff --git a/resources/libraries/bash/entry/check/gpl_license.sh b/resources/libraries/bash/entry/tox/gpl_license.sh
index 167d3f3ecd..7112075883 100644
--- a/resources/libraries/bash/entry/check/gpl_license.sh
+++ b/resources/libraries/bash/entry/tox/gpl_license.sh
@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
diff --git a/resources/libraries/bash/entry/check/line.sh b/resources/libraries/bash/entry/tox/line.sh
index 6f373121e0..a90fc22cae 100644
--- a/resources/libraries/bash/entry/check/line.sh
+++ b/resources/libraries/bash/entry/tox/line.sh
@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
diff --git a/resources/libraries/bash/entry/check/model_version.sh b/resources/libraries/bash/entry/tox/model_version.sh
index 2bcc628bfb..2bcc628bfb 100644
--- a/resources/libraries/bash/entry/check/model_version.sh
+++ b/resources/libraries/bash/entry/tox/model_version.sh
diff --git a/resources/libraries/bash/entry/check/new_line.sh b/resources/libraries/bash/entry/tox/new_line.sh
index 4857f9f8bd..a8fb38f73e 100644
--- a/resources/libraries/bash/entry/check/new_line.sh
+++ b/resources/libraries/bash/entry/tox/new_line.sh
@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
diff --git a/resources/libraries/bash/entry/check/pylint.sh b/resources/libraries/bash/entry/tox/pylint.sh
index fbfea4773e..a3e0f8ee14 100644
--- a/resources/libraries/bash/entry/check/pylint.sh
+++ b/resources/libraries/bash/entry/tox/pylint.sh
@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
diff --git a/tox.ini b/tox.ini
index 079e689136..126af2d454 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Cisco and/or its affiliates.
+# Copyright (c) 2022 Cisco and/or its affiliates.
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at:
@@ -20,9 +20,9 @@
 # Usage:
 # cd to CSIT root (other directories might use different tox.ini)
 #   $ tox
-# will execute all checks.
+# will execute all default checkers.
 #  $ tox -e pylint
-# will execute only checks defined in "pylint" tox environment.
+# will execute only checkers (or fixers) defined in "pylint" tox environment.
 
 [tox]
 # Fast and brief checkers to front, slow or verbose checkers to back.
@@ -32,48 +32,48 @@ envlist = job_spec, copyright_year, gpl_license, model_version,
 # The following is needed as tox requires setup.py by default.
 skipsdist = true
 # Just a shorthand to avoid long lines.
-checker_dir = ./resources/libraries/bash/entry/check
+script_dir = ./resources/libraries/bash/entry/tox
 
 # TODO: Tox prints various warnings. Figure them out and fix them.
 
 # Recommended ordering withinn testenv definition:
 # + General comments.
 # + ignore_outcome for non-voting checkers,
-# + setenv (PYTHONPATH) for Python-using checkers.
+# + setenv (PYTHONPATH) for Python-using checkers and fixers.
 # + Other Python stuff (e.g. basepython and deps for pylint).
 # + whitelist_externals to enable bash.
-# + commands with a single bash to launch the corresponding checker script.
+# + Commands with a single bash to launch the corresponding script.
 
 # Keep testenvs sorted alphabetically, please.
 
 [testenv:autogen]
 setenv = PYTHONPATH = {toxinidir}
 whitelist_externals = /bin/bash
-commands = bash {[tox]checker_dir}/autogen.sh
+commands = bash {[tox]script_dir}/autogen.sh
 
 [testenv:copyright_year]
 whitelist_externals = /bin/bash
-commands = bash {[tox]checker_dir}/copyright_year.sh
+commands = bash {[tox]script_dir}/copyright_year.sh
 
 [testenv:doc_verify]
 # Fix all documentation error before enabling voting.
 ignore_outcome = true
 whitelist_externals = /bin/bash
-commands = bash {[tox]checker_dir}/doc_verify.sh
+commands = bash {[tox]script_dir}/doc_verify.sh
 
 [testenv:gpl_license]
 whitelist_externals = /bin/bash
-commands = bash {[tox]checker_dir}/gpl_license.sh
+commands = bash {[tox]script_dir}/gpl_license.sh
 
 [testenv:line_length]
 # Fix all transgressions and remove the ignore_outcome flag.
 ignore_outcome = true
 whitelist_externals = /bin/bash
-commands = bash {[tox]checker_dir}/line.sh
+commands = bash {[tox]script_dir}/line.sh
 
 [testenv:model_version]
 whitelist_externals = /bin/bash
-commands = bash {[tox]checker_dir}/model_version.sh
+commands = bash {[tox]script_dir}/model_version.sh
 
 [testenv:new_line_length]
 # Adding .svg, big .rst tables, .yaml and similar still requires long lines.
@@ -81,7 +81,7 @@ commands = bash {[tox]checker_dir}/model_version.sh
 # the checker has to remain non-voting.
 ignore_outcome = true
 whitelist_externals = /bin/bash
-commands = bash {[tox]checker_dir}/new_line.sh
+commands = bash {[tox]script_dir}/new_line.sh
 
 [testenv:pylint]
 # Run pylint, but hide its return value until python warnings are cleared.
@@ -92,7 +92,7 @@ deps =
     pylint==2.4.3
     -r ./requirements.txt
 whitelist_externals = /bin/bash
-commands = bash {[tox]checker_dir}/pylint.sh
+commands = bash {[tox]script_dir}/pylint.sh
 
 # Keep testenvs sorted alphabetically, please.
 
@@ -105,5 +105,5 @@ commands = bash {[tox]checker_dir}/pylint.sh
 # TODO: Create .yaml specific checker, so people can override long line check.
 # TODO: Create .rst specific checker, if there is one allowing
 #       to override line check.
-# TODO: You get the idea, replace line check with something smarter
+# TODO: You get the idea, replace line checker with something smarter
 #       wherever possible.