Merge "make help target cleanup"
diff --git a/Makefile b/Makefile
index b205054..ecdaebc 100644
--- a/Makefile
+++ b/Makefile
@@ -16,16 +16,15 @@
 # -----------------------------------------------------------------------
 
 # Makefile for testing JJB jobs in a virtualenv
-.PHONY: all clean help test
-.DEFAULT_GOAL := all
-# .DEFAULT_GOAL := lint-jjb
+.PHONY: help clean help test
+.DEFAULT_GOAL := help
 
 ##-------------------##
 ##---]  GLOBALS  [---##
 ##-------------------##
 TOP          ?= .
 MAKEDIR      ?= $(TOP)/makefiles
-export SHELL := bash -e -o pipefail
+export SHELL := bash -e -o pipefail#    # [TODO] remove once set -u cleaned up
 
 ##--------------------##
 ##---]  INCLUDES  [---##
@@ -42,6 +41,8 @@
 	mkdir $@
 
 ## -----------------------------------------------------------------------
+## Intent: Sanity check incoming JJB config changes.
+##   Todo: Depend on makefiles/lint/jjb.mk :: lint-jjb
 ## -----------------------------------------------------------------------
 # lint : lint-jjb
 lint-tox:
@@ -61,6 +62,7 @@
 clean:
 	$(RM) -r $(JOBCONFIG_DIR)
 
+## Display make help late
 include $(ONF_MAKE)/help/trailer.mk
 
 # [EOF]
diff --git a/makefiles/consts.mk b/makefiles/consts.mk
index 4e3e24d..bac4362 100644
--- a/makefiles/consts.mk
+++ b/makefiles/consts.mk
@@ -30,8 +30,9 @@
 # [DEBUG] make {target} HIDE=
 HIDE        ?= @
 
-env-clean   = /usr/bin/env --ignore-environment
-xargs-n1    := xargs -0 -t -n1 --no-run-if-empty
+env-clean      ?= /usr/bin/env --ignore-environment
+xargs-n1       := xargs -0 -t -n1 --no-run-if-empty
+xargs-n1-clean := $(env-clean) $(xargs-n1)
 
 ## -----------------------------------------------------------------------
 ## Default shell:
@@ -44,6 +45,8 @@
 $(if $(have-shell-bash),$(null),\
   $(eval export SHELL := bash -euo pipefail))
 
+export SHELL ?= bash -euo pipefail
+
 $(if $(DEBUG),$(warning LEAVE))
 
 # [EOF]
diff --git a/makefiles/gerrit/help.mk b/makefiles/gerrit/help.mk
new file mode 100644
index 0000000..2ba155b
--- /dev/null
+++ b/makefiles/gerrit/help.mk
@@ -0,0 +1,30 @@
+# -*- makefile -*-
+# -----------------------------------------------------------------------
+# Copyright 2021-2023 Open Networking Foundation (ONF) and the ONF Contributors
+#
+# 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.
+# -----------------------------------------------------------------------
+
+# -----------------------------------------------------------------------
+# -----------------------------------------------------------------------
+help-summary ::
+	@echo '  help-gerrit         Display help for gerrit targets'
+
+help-verbose :: help-gerrit
+
+help-gerrit:
+	@echo
+	@echo '[GERRIT]'
+	@echo '  replication-status  Report sync status of the gerrit-to-github mirror.'
+
+# [EOF]
diff --git a/makefiles/gerrit/include.mk b/makefiles/gerrit/include.mk
new file mode 100644
index 0000000..54e5895
--- /dev/null
+++ b/makefiles/gerrit/include.mk
@@ -0,0 +1,44 @@
+# -*- makefile -*-
+# -----------------------------------------------------------------------
+# Copyright 2021-2023 Open Networking Foundation (ONF) and the ONF Contributors
+#
+# 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.
+# -----------------------------------------------------------------------
+
+##--------------------##
+##---]  INCLUDES  [---##
+##--------------------##
+include $(MAKEDIR)/gerrit/help.mk
+
+# -----------------------------------------------------------------------
+# -----------------------------------------------------------------------
+replication-status:
+	ssh gerrit.opencord.org replication list --detail
+
+# -----------------------------------------------------------------------
+# NOTE: Gerrit ssh targets assume use of ~/.ssh config files
+#       port, login, etc are 
+# -----------------------------------------------------------------------
+# % ssh -p 29418 <username>@gerrit.opencord.org replication list --detail
+# % ssh gerrit.opencord.org replication list --detail
+# -----------------------------------------------------------------------
+# Host gerrit.opencord.org
+#  Hostname gerrit.opencord.org
+#  IdentityFile ~/.ssh/gerrit.opencord.org/{ssh_keyfile}
+#  IdentitiesOnly yes
+#  AddKeysToAgent yes
+#  Port 29418
+#  User tux@opennetworking.org
+# -----------------------------------------------------------------------
+
+# [EOF]
diff --git a/makefiles/git-submodules.mk b/makefiles/git-submodules.mk
index 24ad2b0..656d8b4 100644
--- a/makefiles/git-submodules.mk
+++ b/makefiles/git-submodules.mk
@@ -60,11 +60,12 @@
 help ::
 	@echo
 	@echo '[GIT-SUBMODULES]'
-	@echo '  submodules     Checkout dependent git submodules'
+	@echo '  reload              Setup to auto-reload sphinx doc changes in browser'
+	@echo '  submodules          Checkout dependent git submodules'
   ifdef VERBOSE
-	@echo '  global-jjb     Checkout ci-management submodule global-jjb'
-	@echo '  lf-ansible     Checkout ci-management submodule lf-ansible'
-	@echo '  packer         Checkout ci-management submodule packer'
+	@echo '  global-jjb          Checkout ci-management submodule global-jjb'
+	@echo '  lf-ansible          Checkout ci-management submodule lf-ansible'
+	@echo '  packer              Checkout ci-management submodule packer'
   endif
 
 ## -----------------------------------------------------------------------
diff --git a/makefiles/help/include.mk b/makefiles/help/include.mk
index 4450784..3134a38 100644
--- a/makefiles/help/include.mk
+++ b/makefiles/help/include.mk
@@ -15,17 +15,73 @@
 # limitations under the License.
 # -----------------------------------------------------------------------
 
-# Parent makefile should include this early so help
-# message will be prefixed by a usage statement.
-help ::
+##-------------------##
+##---]  GLOBALS  [---##
+##-------------------##
+.PHONY: help help-summary help-simple help-verbose
+
+##-------------------##
+##---]  TARGETS  [---##
+##-------------------##
+
+## -----------------------------------------------------------------------
+## Intent: Render topic/tool based makefile help
+## -----------------------------------------------------------------------
+## Three targets are used to render conditional makefile help
+##    help-summary      A one-line target summary for the topic
+##    help-simple       Common targets for the topic (lint-helm, build, test)
+##    help-verbose      Exhaustive display of supported targets
+## -----------------------------------------------------------------------
+## [COOKBOOK]
+##   help colon-colon   All 'help' targets are evaluated for 'make help'
+##   help-banner        Display a usage banner for help
+##   help-summary       Display all one-line topic summary help
+##     [conditonal]
+##   help-simple        Display all common topic makefile targets.
+##   help-verbose       Exhaustive display of makefile target help.
+##     VERBOSE=
+## -----------------------------------------------------------------------
+## [See Also] makefiles/gerrit/{include.mk, help.mk}
+##   help-gerrit        Summary targets can always be used to display topic help
+##   help-verbose       Exhaustive gerrit target display.
+## -----------------------------------------------------------------------
+help :: help-banner help-summary
+
+## -----------------------------------------------------------------------
+## Intent: Display a usage banner for help.  Target will be evaluated
+##         before all other help display.
+## -----------------------------------------------------------------------
+help-banner:
 	@echo "Usage: $(MAKE) [options] [target] ..."
+
+## -----------------------------------------------------------------------
+## Intent: Display extended help.
+## -----------------------------------------------------------------------
+## Question:
+##   o Help display can be long based on volume of targets.
+##   o Should a 3rd case be added to display:
+##      - help-simple (one-liner help) by default
+##      - conditional display of extended help:
+##          - help-simple or help-verbose
+##   o Current logic displays extended help by default.
+## -----------------------------------------------------------------------
+ifdef VERBOSE
+  help :: help-verbose
+else
+  help :: help-simple
+endif
+
+## -----------------------------------------------------------------------
+## Intent: Display simple extended target help
+## -----------------------------------------------------------------------
+help-simple ::
 	@echo
 	@echo '[VIEW]'
-	@echo '  reload                 Setup to auto-reload sphinx doc changes in browser'
-	@echo '  view-html              View generated documentation'
+	@echo '  reload              Setup to auto-reload sphinx doc changes in browser'
+	@echo '  view-html           View generated documentation'
 	@echo
 	@echo '[TEST]'
-	@echo '  test                   make lint linkcheck'
-	@echo '  test-all               make all-generation-targets'
+	@echo "  test                $(MAKE) lint linkcheck"
+	@echo "  test-all            $(MAKE) all-generation-targets"
 
 # [EOF]
diff --git a/makefiles/help/trailer.mk b/makefiles/help/trailer.mk
index dac7e15..c24934f 100644
--- a/makefiles/help/trailer.mk
+++ b/makefiles/help/trailer.mk
@@ -20,14 +20,14 @@
 help ::
 	@echo
 	@echo '[CLEAN]'
-	@echo '  clean          Remove generated targets'
-	@echo '  sterile        clean + remove virtual env interpreter install'
+	@echo '  clean               Remove generated targets'
+	@echo '  sterile             clean + remove virtual env interpreter install'
 
 help ::
 	@echo
 	@echo '[HELP]'
-	@echo '  help           Display program help'
-	@echo '  help-verbose   Display additional targets and help'
+	@echo '  help                Display program help'
+	@echo '  help-verbose        Display additional targets and help'
 
 help ::
 	@echo
diff --git a/makefiles/help/variables.mk b/makefiles/help/variables.mk
index 80171a7..a22b179 100644
--- a/makefiles/help/variables.mk
+++ b/makefiles/help/variables.mk
@@ -31,6 +31,6 @@
 	@echo '[VARIABLES] - Conditional makefile behavior'
 	@echo '  NO_PATCHES=           Do not apply patches to the python virtualenv'
 	@echo '  NO_OTHER_REPO_DOCS=   No foreign repos, only apply target to local sources.'
-	@echo '  VERBOSE=              Display extended help'
+	@echo '  VERBOSE=              Display extended help topics'
 
 # [EOF]
diff --git a/makefiles/include.mk b/makefiles/include.mk
index 18ff197..339d367 100644
--- a/makefiles/include.mk
+++ b/makefiles/include.mk
@@ -33,6 +33,7 @@
 include $(ONF_MAKE)/virtualenv.mk#        # lint-{jjb,python} depends on venv
 include $(ONF_MAKE)/lint/include.mk
 include $(ONF_MAKE)/git-submodules.mk
+include $(ONF_MAKE)/gerrit/include.mk
 include $(ONF_MAKE)/todo.mk
 include $(ONF_MAKE)/help/variables.mk
 
diff --git a/makefiles/lint/help.mk b/makefiles/lint/help.mk
new file mode 100644
index 0000000..24a5aa1
--- /dev/null
+++ b/makefiles/lint/help.mk
@@ -0,0 +1,31 @@
+# -*- makefile -*-
+# -----------------------------------------------------------------------
+# Copyright 2021-2023 Open Networking Foundation (ONF) and the ONF Contributors
+#
+# 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.
+# -----------------------------------------------------------------------
+
+help ::
+
+# -----------------------------------------------------------------------
+# -----------------------------------------------------------------------
+help-summary ::
+	@echo '  help-lint           Display lint target help'
+
+help-simple :: help-lint
+help-lint  :
+	@echo
+	@echo "[LINT]"
+	@echo '  help-lint           Display lint target help'
+
+# [EOF]
diff --git a/makefiles/lint/include.mk b/makefiles/lint/include.mk
index aa6867b..66834a6 100644
--- a/makefiles/lint/include.mk
+++ b/makefiles/lint/include.mk
@@ -13,6 +13,7 @@
 include $(ONF_MAKE)/lint/makefile.mk
 include $(ONF_MAKE)/lint/python.mk
 include $(ONF_MAKE)/lint/shell.mk
+include $(ONF_MAKE)/lint/help.mk
 
 ifdef YAML_FILES
   include $(ONF_MAKE)/lint/yaml/python.mk
diff --git a/makefiles/lint/makefile.mk b/makefiles/lint/makefile.mk
index 8ebe9c3..6e1d80a 100644
--- a/makefiles/lint/makefile.mk
+++ b/makefiles/lint/makefile.mk
@@ -1,6 +1,18 @@
 # -*- makefile -*-
 # -----------------------------------------------------------------------
-# Copyright 2022 Open Networking Foundation (ONF) and the ONF Contributors
+# Copyright 2017-2023 Open Networking Foundation (ONF) and the ONF Contributors
+#
+# 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.
 # -----------------------------------------------------------------------
 
 ##-------------------##
@@ -32,14 +44,16 @@
 endif
 
 ## -----------------------------------------------------------------------
+## Intent: Perform a lint check on makefile sources
 ## -----------------------------------------------------------------------
 lint-make:
 	$(HIDE)$(env-clean) $(make-check-find) \
 	    | $(xargs-n1-local) $(make-check) $(make-check-args)
 
 ## -----------------------------------------------------------------------
+## Intent: Display command help
 ## -----------------------------------------------------------------------
-help ::
-	@echo '  lint-make                     Syntax check [Mm]akefile and *.mk'
+help-summary ::
+	@echo '  lint-make           Syntax check [Mm]akefile and *.mk'
 
 # [EOF]
diff --git a/makefiles/lint/python.mk b/makefiles/lint/python.mk
index a3d651c..d3fe4fd 100644
--- a/makefiles/lint/python.mk
+++ b/makefiles/lint/python.mk
@@ -1,6 +1,6 @@
 # -*- makefile -*-
 # -----------------------------------------------------------------------
-# Copyright 2022 Open Networking Foundation (ONF) and the ONF Contributors
+# Copyright 2022-2023 Open Networking Foundation (ONF) and the ONF Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -38,14 +38,16 @@
 endif
 
 ## -----------------------------------------------------------------------
+## Intent: Perform a lint check on makefile sources
 ## -----------------------------------------------------------------------
 lint-python:
 	$(HIDE)$(env-clean) $(python-check-find) \
 	    | $(xargs-n1) $(python-check) $(python-check-args)
 
 ## -----------------------------------------------------------------------
+## Intent: Display command help
 ## -----------------------------------------------------------------------
-help ::
-	@echo '  lint-python                   Syntax check python sources'
+help-summary ::
+	@echo '  lint-python         Syntax check python sources (*.py)'
 
 # [EOF]
diff --git a/makefiles/lint/shell.mk b/makefiles/lint/shell.mk
index cadc084..b1a083b 100644
--- a/makefiles/lint/shell.mk
+++ b/makefiles/lint/shell.mk
@@ -1,6 +1,18 @@
 # -*- makefile -*-
 # -----------------------------------------------------------------------
-# Copyright 2022 Open Networking Foundation (ONF) and the ONF Contributors
+# Copyright 2022-2023 Open Networking Foundation (ONF) and the ONF Contributors
+#
+# 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.
 # -----------------------------------------------------------------------
 
 ##-------------------##
@@ -28,6 +40,7 @@
 endif
 
 ## -----------------------------------------------------------------------
+## Intent: Perform a lint check on command line script sources
 ## -----------------------------------------------------------------------
 lint-shell:
 	$(shell-check) -V
@@ -36,8 +49,9 @@
 	    | $(xargs-n1) $(shell-check) $(shell-check-args)
 
 ## -----------------------------------------------------------------------
+## Intent: Display command help
 ## -----------------------------------------------------------------------
-help ::
-	@echo '  lint-shell                    Syntax check shell sources'
+help-summary ::
+	@echo '  lint-shell          Syntax check shell sources'
 
 # [EOF]
diff --git a/makefiles/lint/yaml.mk b/makefiles/lint/yaml.mk
index 00241b3..b60e616 100644
--- a/makefiles/lint/yaml.mk
+++ b/makefiles/lint/yaml.mk
@@ -27,6 +27,6 @@
 	    ; yamllint -s $(YAML_FILES)
 
 help::
-	@echo "  lint-yaml            Syntax check yaml source using yamllint"
+	@echo "  lint-yaml           Syntax check yaml source using yamllint"
 
 # [EOF]
diff --git a/makefiles/lint/yaml/python.mk b/makefiles/lint/yaml/python.mk
index 868d9b7..316afd3 100644
--- a/makefiles/lint/yaml/python.mk
+++ b/makefiles/lint/yaml/python.mk
@@ -1,6 +1,6 @@
 # -*- makefile -*-
 # -----------------------------------------------------------------------
-# Copyright 2022 Open Networking Foundation (ONF) and the ONF Contributors
+# Copyright 2022-2023 Open Networking Foundation (ONF) and the ONF Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# SPDX-FileCopyrightText: 2022 Open Networking Foundation (ONF) and the ONF Contributors
+# SPDX-FileCopyrightText: 2022-2023 Open Networking Foundation (ONF) and the ONF Contributors
 # SPDX-License-Identifier: Apache-2.0
 # -----------------------------------------------------------------------
 
@@ -32,10 +32,16 @@
 lint-yaml: $(venv-activate)
 lint-yaml: $(lint-yaml-dep)
 
+## -----------------------------------------------------------------------
+## Intent: Perform a lint check on yaml sources
+## -----------------------------------------------------------------------
 $(lint-yaml-dep):
 	$(vst-env) && yamllint -s $(call lint-yaml-src,$@)
 
-help::
-	@echo "  lint-yaml            Syntax check yaml sources"
+## -----------------------------------------------------------------------
+## Intent: Display command help
+## -----------------------------------------------------------------------
+help-summary ::
+	@echo '  lint-yaml           Syntax check yaml sources (python -M yaml)'
 
 # [EOF]
diff --git a/makefiles/lint/yaml/yamllint.mk b/makefiles/lint/yaml/yamllint.mk
index 6782c74..dc4e015 100644
--- a/makefiles/lint/yaml/yamllint.mk
+++ b/makefiles/lint/yaml/yamllint.mk
@@ -1,6 +1,6 @@
 # -*- makefile -*-
 # -----------------------------------------------------------------------
-# Copyright 2022 Open Networking Foundation (ONF) and the ONF Contributors
+# Copyright 2022-2023 Open Networking Foundation (ONF) and the ONF Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# SPDX-FileCopyrightText: 2022 Open Networking Foundation (ONF) and the ONF Contributors
+# SPDX-FileCopyrightText: 2022-2023 Open Networking Foundation (ONF) and the ONF Contributors
 # SPDX-License-Identifier: Apache-2.0
 # -----------------------------------------------------------------------
 
@@ -41,15 +41,18 @@
 yamllint-find += -print0
 
 ## -----------------------------------------------------------------------
+## Intent: Perform a lint check on yaml sources
 ## -----------------------------------------------------------------------
 lint lint-yaml:
 	$(HIDE)$(env-clean) $(yamllint-find) \
-	    | xargs -0 --no-run-if-empty -t -n1 $(yamllint) $(yamllint-args)
+	    | $(xargs-n1-clean) -t $(yamllint) $(yamllint-args)
+#	    | xargs -0 --no-run-if-empty -t -n1 $(yamllint) $(yamllint-args)
 
 ## -----------------------------------------------------------------------
+## Intent: Display command help
 ## -----------------------------------------------------------------------
 help::
-	@echo "  lint-yaml                     Syntax check yaml sources"
+	@echo "  lint-yaml           Syntax check yaml sources (yamllint)"
 
 $(if $(DEBUG),$(warning ENTER))
 
diff --git a/makefiles/todo.mk b/makefiles/todo.mk
index 218b878..d97dbbb 100644
--- a/makefiles/todo.mk
+++ b/makefiles/todo.mk
@@ -27,7 +27,7 @@
 ## -----------------------------------------------------------------------
 ## -----------------------------------------------------------------------
 help ::
-	@echo '  todo                          Display future enhancement list.'
+	@echo '  todo                Display future enhancement list.'
 
 $(if $(DEBUG),$(warning LEAVE))
 
diff --git a/makefiles/virtualenv.mk b/makefiles/virtualenv.mk
index 43a4e67..628f166 100644
--- a/makefiles/virtualenv.mk
+++ b/makefiles/virtualenv.mk
@@ -62,8 +62,8 @@
 help ::
 	@echo
 	@echo '[VIRTUAL ENV]'
-	@echo '  venv                         Create a python virtual environment'
-	@echo '    venv-name=                 Subdir name for virtualenv install'
+	@echo '  venv                Create a python virtual environment'
+	@echo '    venv-name=        Subdir name for virtualenv install'
 	@echo '  venv-activate-script         make macro name'
 	@echo '      $$(target) dependency    install python virtualenv'
 	@echo '      source $$(macro) && cmd  configure env and run cmd'