Update search tool help.
jira/bin/jira-search.sh
-----------------------
o Help text growing long, refactor help text into jira-search/help.
o Added command line switches --help-* and --usage-*
jira/jira-search/help/utils.sh
------------------------------
o Added library functions for displaying context help.
o Display switch permutations for a given prefix.
o Display use cases for a given switch.
jira/jira-search/help/fixversion.switches
jira/jira-search/help/resolved.sh
jira/jira-search/help/resolved.switches
jira/jira-search/help/resolved.usage
jira/jira-search/help/user.switches
jira/jira-search/help/user.usage
-----------------------------------------
o Switch help and usage text.
Change-Id: I0cd34475521c2b42054fbe4e7966a6d3767f8f89
diff --git a/jira/bin/jira-search.sh b/jira/bin/jira-search.sh
index 97b8cc2..462df4d 100755
--- a/jira/bin/jira-search.sh
+++ b/jira/bin/jira-search.sh
@@ -1,4 +1,21 @@
#!/bin/bash
+# -----------------------------------------------------------------------
+# Copyright 2023-2024 Open Networking Foundation 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.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2023-2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
## --------------------------------------------------------------------
## Intent: Construct a jira ticket query with attributes
## --------------------------------------------------------------------
@@ -7,6 +24,9 @@
declare pgm=''
pgm="$(realpath --canonicalize-existing "$0")"
+ # stack-trace-on-error
+ # interrupt handler
+ # mkdir with auto-cleanup at exit
declare root=''
root="${pgm%%/jira/bin/jira-search.sh}"
source "$root/lf/onf-common/common.sh" '--common-args-begin--'
@@ -16,6 +36,9 @@
pgm_bin="${root}/bin"
readonly pgm_bin
+
+ pgm_help="${root}/jira/jira-search/help"
+ readonly pgm_help
}
# set -euo pipefail
@@ -43,6 +66,7 @@
#source "$pgmlib/resolved.sh"
source "${pgm_lib}/fixversion.sh"
source "${pgm_lib}/resolved.sh"
+source "${pgm_lib}/help/utils.sh"
## --------------------------------------------------------------------
## --------------------------------------------------------------------
@@ -331,36 +355,28 @@
[SERVER]
--server {cord,onf}
- --onf jira.opennetworking.org (default)
+ --onf jira.opennetworking.org
--opencord jira.opencord.org
[WHAT]
--component Search by component name assigned to ticket
--label Search by label name assigned to ticket.
--text Search string(s)
+EOH
-[FIXVERSION] - Voltha-v2.12
- --fixversion-incl
- --fixversion-excl
- --fixversion-is-empty
- --fixversion-not-empty
+# declare -a topics=()
+# topics+=('fixversion.switches')
+# topics+=('resolved.switches')
+#
+# help_switch_show "${topics[@]}"#
+ #
+#[USER(s)]
+# --me Tickets assigned to or reported by me.
+# --user [u] Tickets assigned to this user.
+# --nobody Raw query, no filtering by user
-[RESOLVED] - tokens={Declined, Won't Fix}
- --resolved-start ccyy-mm-dd
- --resolved-end ccyy-mm-dd
- --resolved-incl {token(s)}
- --resolved-excl {token(s)}
- --resolved-is-empty Query for open tickets
- --resolved-not-empty
-[USER(s)]
- --me Tickets assigned to or reported by me.
- --user [u] Tickets assigned to this user.
- --nobody Raw query, no filtering by user
-
-[BY-USER]
- --assigned Tickets assided to user
- --reported Tickets created by user
+ cat <<EOH
[BOOL]
--and Join terms using 'AND'
@@ -376,17 +392,26 @@
--text-or [t] Any of these terms
[RANGE]
- --newer [d] Search for tickets created < [n] days ago.
- --older [d] Search for tickets created > [n] days ago.
+ --newer [d] Search for tickets created < [n] days ago.
+ --older [d] Search for tickets created > [n] days ago.
[ALIASES]
- --all Query for all unresolved tickets
+ --all Query for all unresolved tickets
+
+[TOPIC]
+ --fixversion Query by field: fixedversion
+ --resolved Query by field: resolved
+ --user Query by owner, requestor or 'my' jira tickets.
+
+[HELP]
+ --help This message
+ --help-{topic} Display switch help and use case. (--help-resolved)
+ --usage-{topic} Display use cases for a given switch (--usage-user)
[USAGE]
- $0 --assigned
+ $0 --opencord --assigned --unresolved
o Display all tickets assigned to my login
- $0 --requested --user tux
- o Display all tickets requested by user tux
+
$0 --reported --or --text 'bbsim' --text 'release'
o Search for tickets that contain strings bbsim or release
$0 --cord --text-and 'release' --text-and 'voltctl'
@@ -430,7 +455,10 @@
case "$arg" in
- -*help) usage; exit 0 ;;
+ '--help') usage; exit 0 ;;
+ '--help-'*) help_with "${arg/--help-/}" ;;
+ '--usage-'*) help_usage_show "${arg/--usage-/}"
+ ;;
##-----------------##
##---] MODES [---##
@@ -438,6 +466,16 @@
-*debug) declare -g -i debug=1 ;;
--dry-run) declare -g -i dry_run=1 ;;
+ ##------------------------##
+ ##---] SWITCH ALIAS [---##
+ ##------------------------##
+ --unresolved)
+ declare -a args=()
+ args+=('--resolved-is-empty')
+ [[ $# -gt 0 ]] && { args+=("$@"); }
+ set -- "${args[@]}"
+ ;;
+
##-------------------##
##---] BY USER [---##
##-------------------##
@@ -462,8 +500,8 @@
esac
;;
- --onf) declare server='jira.opennetworking.org' ;;
- --cord) declare server='jira.opencord.org' ;;
+ --onf) declare server='jira.opennetworking.org' ;;
+ --opencord) declare server='jira.opencord.org' ;;
##---------------------##
##---] SEARCH-BY [---##
@@ -534,7 +572,7 @@
esac
;;
- --resolved-*)
+ '--resolved-'*)
# function get_jql_reasons()
case "$arg" in
diff --git a/jira/jira-search/help/fixversion.switches b/jira/jira-search/help/fixversion.switches
new file mode 100644
index 0000000..9ddc4a2
--- /dev/null
+++ b/jira/jira-search/help/fixversion.switches
@@ -0,0 +1,27 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation 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.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[FIXVERSION] - Voltha-v2.12
+ --fixversion-incl
+ --fixversion-excl
+ --fixversion-is-empty
+ --fixversion-not-empty
+# [EOF]
diff --git a/jira/jira-search/help/resolved.sh b/jira/jira-search/help/resolved.sh
new file mode 100644
index 0000000..4f0124f
--- /dev/null
+++ b/jira/jira-search/help/resolved.sh
@@ -0,0 +1,35 @@
+#!/bin/bash
+# -----------------------------------------------------------------------
+# Copyright 2023-2024 Open Networking Foundation 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.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2023-2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent: Construct a jira ticket query with attributes
+## --------------------------------------------------------------------
+
+function resolved_switches()
+{
+ local ref=$1; shift
+
+
+[RESOLVED] - tokens={Declined, Won't Fix}
+ --resolved-start ccyy-mm-dd
+ --resolved-end ccyy-mm-dd
+ --resolved-incl {token(s)}
+ --resolved-excl {token(s)}
+ --resolved-is-empty Query for open tickets
+ --resolved-not-empty
+ --unresolved Alias for resolved-is-empty
diff --git a/jira/jira-search/help/resolved.switches b/jira/jira-search/help/resolved.switches
new file mode 100644
index 0000000..86c49d3
--- /dev/null
+++ b/jira/jira-search/help/resolved.switches
@@ -0,0 +1,30 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation 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.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[RESOLVED] - tokens={Declined, Won't Fix}
+ --resolved-start ccyy-mm-dd
+ --resolved-end ccyy-mm-dd
+ --resolved-incl {token(s)}
+ --resolved-excl {token(s)}
+ --resolved-is-empty Query for open tickets
+ --resolved-not-empty
+ --unresolved Alias for --resolved-if-empty
+# [EOF]
diff --git a/jira/jira-search/help/resolved.usage b/jira/jira-search/help/resolved.usage
new file mode 100644
index 0000000..fad5dbb
--- /dev/null
+++ b/jira/jira-search/help/resolved.usage
@@ -0,0 +1,29 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation 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.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[RESOLVED]
+ $0 --server opencord --component bbsim --unresolved
+ $0 --server opencord --component bbsim --resolved-is-empty
+ o Query for open bbsim tickets.
+
+ $0 --proj VOL --fixversion "VOLTHA v2.12" --resolved-is-empty
+ o Query for unresolved v2.12 release tickets.
+# [EOF]
diff --git a/jira/jira-search/help/user.switches b/jira/jira-search/help/user.switches
new file mode 100644
index 0000000..38661e1
--- /dev/null
+++ b/jira/jira-search/help/user.switches
@@ -0,0 +1,30 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation 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.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[USER(s)]
+ --me Tickets assigned to or reported by me.
+ --user [u] Tickets assigned to this user.
+ --nobody Raw query, no filtering by user
+
+[BY-USER]
+ --assigned Tickets assided to user
+ --reported Tickets created by user
+# [EOF]
diff --git a/jira/jira-search/help/user.usage b/jira/jira-search/help/user.usage
new file mode 100644
index 0000000..d94f374
--- /dev/null
+++ b/jira/jira-search/help/user.usage
@@ -0,0 +1,39 @@
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation 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.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+[USER]
+ $0 --server opencord --unresolved --assigned --user tux
+ o Display all tickets assigned to user tux
+
+ $0 --server opencord --requested --user tux
+ o Display all tickets requested by user tux
+
+ $0 --server opencord --unresolved --user tux
+ o Display open tickets assigned or requested by user tux.
+
+[BY USER]
+ $0 --server-opencord --assigned --unresolved
+ o Display all open tickets assigned to my login
+
+ $0 --server opencord --me
+ o Display tickets requested or assigned to my login.
+
+# [EOF]
diff --git a/jira/jira-search/help/utils.sh b/jira/jira-search/help/utils.sh
new file mode 100644
index 0000000..53b237d
--- /dev/null
+++ b/jira/jira-search/help/utils.sh
@@ -0,0 +1,90 @@
+#!/bin/bash
+# -----------------------------------------------------------------------
+# Copyright 2024 Open Networking Foundation 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.
+# -----------------------------------------------------------------------
+# SPDX-FileCopyrightText: 2024 Open Networking Foundation Contributors
+# SPDX-License-Identifier: Apache-2.0
+## --------------------------------------------------------------------
+## Intent:
+## --------------------------------------------------------------------
+
+## --------------------------------------------------------------------
+## --------------------------------------------------------------------
+function help_read()
+{
+ local -n ref=$1; shift
+ local path="$1"; shift
+
+ readarray text < <(grep -v -e '^#' "$path")
+ ref+=("${text[@]}")
+
+ return
+}
+
+## --------------------------------------------------------------------
+## --------------------------------------------------------------------
+function help_switch_show()
+{
+ local -a buffer=()
+
+ local helpwith
+ for helpwith in "$@"; do
+ local path="$pgm_help/${helpwith}.switches"
+ if [[ ! -e "$path" ]]; then
+ readarray fyls < <(find "$pgm_help" -name '*.switches')
+ echo "--usage-${helpwith} does not exist"
+ echo "Try one of:"
+ printf " %s\n" "${fyls[@]}"
+ error "OUTA HERE"
+ fi
+ help_read buffer "$path"
+ done
+
+ printf '%s' "${buffer[@]}"
+ return
+}
+
+## --------------------------------------------------------------------
+## --------------------------------------------------------------------
+function help_usage_show()
+{
+ local -a buffer=()
+
+ local helpwith
+ for helpwith in "$@"; do
+ local path="$pgm_help/${helpwith}.usage"
+ if [[ ! -e "$path" ]]; then
+ readarray fyls < <(find "$pgm_help" -name '*.usage')
+ echo "--usage-${helpwith} does not exist"
+ echo "Try one of:"
+ printf " %s\n" "${fyls[@]}"
+ error "OUTA HERE"
+ fi
+ help_read buffer "$path"
+ done
+
+ printf '%s' "${buffer[@]}"
+ return
+}
+
+## --------------------------------------------------------------------
+## --------------------------------------------------------------------
+function help_with()
+{
+ help_switch_show "$@"
+ help_usage_show "$@"
+}
+
+# [EOF]