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>

1 files changed, 39 insertions, 0 deletions

diff --git a/resources/libraries/bash/entry/tox/README.txt b/resources/libraries/bash/entry/tox/README.txt
new file mode 100644
index 0000000000..e13b60209e
--- /dev/null
+++ b/resources/libraries/bash/entry/tox/README.txt
@@ -0,0 +1,39 @@
+# 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:
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+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 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.
++ Write (to stderr) PASSED or FAILED to help with debugging.
++ Direct more verbose output to appropriately named .log file.
++ Only the output suitable for automated processing by an external caller
+  should be written to stdout.
+++ 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_?