Bash libraries

file bz.sh

Helpful functions to handle bugzilla service interactions

Functions

bz get_bug(bug_id)

Get’s the bug_id bug json information from cache, or if not cached, from the server.

Parameters
  • bug_id: id of the bug to retrieve
Return Value
  • 0:

bz update_bug(bug_id, data...)

Updates the given bug.

Parameters
  • bug_id: id of the bug to update
  • data...: Each of the post parameters to send (usually as name=value).
Return Value
  • 0: if the bug was updated
  • 1: if it was not updated

bz is_revert(commit)

Checks if the given commit is a revert.

Parameters
  • commit: refspec of the commit to check (default=HEAD)
Return Value
  • 0: if the given commit is a revert
  • 1: otherwise

bz get_bug_id(commit)

Extracts the bug ids from the Bug-Url in the given commit.

Note
If the patch is a ‘revert’, it extracts the bug from the reverted commit
Parameters
  • commit: refspec to get the bug from

bz login(bz_user, bz_password)

Logs into bugzilla if not logged in already. 

Options:
    -b bug_id
      If you pass a bug_id, the token for that bug will already be set and
      cached for further reference

    -s server_url
      Use that url instead of the one in the config file
      (https://bugzilla.redhat.com by default)

Configuration parameters:
   bugzilla_server
     full url to the bugzilla server

Parameters
  • bz_user: User to log into bugzilla
  • bz_password: Password

bz get_bug_flags(bugid)

Retrieves all the ‘+’ flags of the given bug.

Parameters
  • bugid: Id of the bug to get the flags from

bz get_bug_status(bugid)

Retrieves the current status of the bug.

Parameters
  • bugid: Id of the bug to retrieve

bz check_flags(bugid, flagspecs...)

Checks that all the flags exist with ‘+’ in the given bug.

Parameters
  • bugid: Id of the bug to check the flags for
  • flagspecs...: can be a single flag or a sequence ot flags separated by ‘|’ to express that those flags are interchangeable, for example flag2|flag2_bis

bz add_tracker(bug_id, tracker_id, external_id, description)

Add a new external bug to the external bugs list.

Parameters
  • bug_id: Id of the bug to update
  • tracker_id: This is the internal tracker id that bugzilla assigns to each external tracker (RHEV gerrit -> 82, oVirt gerrit -> 81)
  • external_id: Id for the bug in the external tracker
  • description: Description to add to the external tracker

bz update_fixed_in_version(bug_id, fixed_in_version)

Update fixed in version field.

Parameters
  • bug_id: Id of the bug to update
  • fixed_in_version: New value for the fixed in version field

bz update_status_and_version(bug_id, bug_status, fixed_in_version, resolution)

Update fixed in version field plus the status field.

Parameters
  • bug_id: Id of the bug to update
  • bug_status: New value for the status field
  • fixed_in_version: New value for the fixed in version field
  • resolution: New value for the resolution

bz update_status(bug_id, new_status, commit_id, resolution)

Legal status transitions:
  NEW|ASSIGNED|MODIFIED -> POST
  POST -> MODIFIED

If it's a revert any source status is allowed

Parameters
  • bug_id: Id of the bug to update
  • new_status: New status to set the bug to, only the allowed transitions will end in a positive result (return code 0)
  • commit_id: Id of the commit that should change the status of this bug
  • resolution: In case that the status is CLOSED, the resolution is needed

bz get_external_bugs(bug_id, external_name)

Parameters
  • bug_id: Id of the parent bug
  • external_name: External string to get the bugs from. If none given it will get all the external bugs. Usually one of:
    • oVirt gerrit
    • RHEV gerrit

bz clean()

Cleans up all the cached config and data. Make sure that your last scripts calls it before exitting.

bz get_product(bug_id)

Prints the product name of the given bug.

Parameters
  • bug_id: Id of the bug to get info about

bz get_classification(bug_id)

Print the classification of the given bug.

Parameters
  • bug_id: Id of the bug to get info about

bz is_private(bug_id)

Parameters
  • bug_id: Id of the bug to check
Return Value
  • 0: if it’s private
  • 1: otherwise

bz get_target_milestone(bug_id)

Print the target milestone of the bug.

Parameters
  • bug_id: Id of the bug to get info about

bz get_target_release(bug_id)

Print the target release of the bug.

Parameters
  • bug_id: Id of the bug to get info about

bz check_target_release(bug_id, branch, tr_match, branch_name)

Example:

 bz.check_target_release 1234 master 'master|3\.3.*' 'master|!3\.[21].*'

 That will check that the bug 1234 target release matches:
      3\.3.*
  And does not match:
      3\.3\.0\..*

  So 3.3.0 or 3.3 will pass but 3.2 and 3.3.0.1 will not

Parameters
  • bug_id: Id of the bug to check the target_release of
  • branch: Name of the current branch
  • tr_match: Tuple in the form ‘branch_name|[!]regexp’
  • branch_name: name of the branch that should check the regexp 
    [!]regexp
    regular expresion to match the target release against, if preceded
     with '!' the expression will be negated
Return Value
  • 1: if the target release and branch defined in tr_match configuration variable do not match the given bug’s target release

bz check_target_milestone(bug_id, branch, tm_match, branch_name)

Example:

  bz.check_target_milestone 1234 master 'master|3\.3.*' 'master|!3\.[21].*'

  That will check that the bug 1234 target milestone matches:
      3\.3.*
  And does not match:
      3\.3\.0\..*

  So 3.3.0 or 3.3 will pass but 3.2 and 3.3.0.1 will not
Return Value
  • 1: if the target milestone and branch defined in tm_match configuration variable do not match the given bug’s target milestone
Parameters
  • bug_id: Id of the bug to get the target_milestone from
  • branch: Name of the current branch
  • tm_match: Tuple in the form branch_name|[!]regexp
  • branch_name: name of the branch that should check the regexp 
    [!]regexp
    regular expresion to match the target milestone against, if preceded
     with '!' the expression will be negated

file conf.sh

Helper configuration functions 

Configuration types
---------------------

There are two types of configurations taken into account, static and
temporary


Static configuration
++++++++++++++++++++++

Static configurations store those values that will persist after each
execution of the hooks, for example users and passwords.


Temporary configurations
++++++++++++++++++++++++++

Some hooks use temporary configurations to store values for other hooks to
recover, for example, when storing cookies.

Configuration hierarchy
++++++++++++++++++++++++

It will source the configuration files in order, skipping any non-existing
ones. The paths where it will look for them are, in source order (the most
prioritary first)::

* $hook_path/$event_type.$chain.conf
* $hook_path/$event_type.conf
* $hook_path/$chain.conf
* $hook_path/conf
* $GERRIT_SITE/hooks/conf
* $HOME/hook/conf
* $hook_path/../../../hooks/conf

When running in gerrit, the $hook_path is usually the git repository of the
project the event was triggered for, for example::

   /home/gerrit2/review_site/git/ovirt-engine.git

Functions

conf _get_conf_files()

Print all the available configuration files from less relevant to more relevant.

conf _get_conf_file()

Print current’s hook config file.

conf get(name, default)

Prints the given key from the config. 

Options:

-c conf_file
  Use that config file
Note
the return code is 1 when the value is not found in the config files, and if specified outputs the default value too
Parameters
  • name: Name of the key to get the value for
  • default: Default value if not found

conf put(name, value)

Writes the given name/value to the configuration. 

Options:

-c conf_file
  Use that config file

Parameters
  • name: Key to store the conf value under
  • value: Value to store

conf load()

Loads the config files from less specific to most so the latest prevails, all the conf entries are loaded as vars. 

Options:

-c conf_file
  Use that config file

conf t_put(key, value)

Temporary config file functions, for the current executione.

Parameters
  • key: Key to store
  • value: Value to store Store the given key/value to temporary storage

conf t_get(key, default)

Print the given key from temporary storage.

Parameters
  • key: Key to store
  • default: Default value to print if not found

conf t_load()

load the temporary config

conf t_clean()

Cleanup the temporary config related temporary files.

file gerrit.sh

Helpful functions to manage gerrit related actions

Functions

gerrit get_patch(patch_id)

Print the bug info.

Note
it is cached for faster access
Parameters
  • patch_id: Patch id to retrieve info, as in 1234 (don’t confuse with the change id)

gerrit is_related(commit)

Check if the patch has the Related-To tag.

Parameters
  • commit: Refspec to check
Return Value
  • 0: if it did not have it
  • 1: otherwise

gerrit parse_params()

Parse all the parameters as env variables, leave the rest as positional args. 

gerrit.parse_params --param1 val1 param2 --param-3 val3
    => [[ param1 == "val1" ]] \
       && [[ param_3 == "val3" ]] \
       && [[ "$1" == "param2" ]]

gerrit review(result, message, project, commit)

Write a review, it will use the env commit and project vars, as set by parse_params.

Parameters
  • result: Value for the verified flag (1, 0, -1)
  • message: Message for the comment
  • project: Gerrit project that owns the commit
  • commit: Refspec for the commit of the patch to write a review for

gerrit status(id)

Print the status of the given patch.

Parameters
  • id: Patch id to get the status for

gerrit is_open(id)

Check if a patch is open.

Parameters
  • id: Patch id to check
Return Value
  • 0: if the patch is open
  • 1: otherwise

gerrit clean(nothing)

Clean up all the temporary files for the current run.

Parameters
  • nothing: No parameters needed

gerrit get_branches(pattern)

Print the list of branches for the current project.

Parameters
  • pattern: If passed, will filter out branches by that pattern (shell-like)

file tools.sh

Helpful miscellaneous functions

Functions

tools is_in(value, elem1...)

Parameters
  • value: Value to look for
  • elem1...: Elements to look among if a value is in the given list of elements

tools trim()

Remove the leading and trailing white spaces.

tools sanitize(word...)

Replace all the bad characters from the given word to fit a bash variable name specification.

Parameters
  • word...: list of words to sanitize

tools hash(what, length)

Get a simple md5 hash of the given string.

Parameters
  • what: Base string for the hash
  • length: Max length for the hash, (default=10)

tools log(message...)

logs the given strings to stderr

Parameters
  • message...: list of messages to log

tools review(cr, ver, msg)

print a review message with the format expeted by the hook dispatcher

Parameters
  • cr: Value for the Code Review flag
  • ver: Value for the Verified flag
  • msg: Message for the review comment

tools match(base_string, match_string)

Parameters
  • base_string: String to check for a match
  • match_string: Tuple in the form ‘[!]regexp’ 
          [!]regexp
          regular expresion to match the base string against, if preceded
           with '!' the expression will be negated

Example:

  tools.match 3.2.1 'master|3\.3.*' 'master|!3\.[21].*'

  That will check that the string 3.2.1 matches:
      3\.3.*
  And does not match:
      3\.3\.0\..*
Return Value
  • TOOLS_MATCHES|0: if the base_string matches all of the match_string passed
  • TOOLS_DOES_NOT_MATCH: if it does not match because of a positive match
  • TOOLS_SHOULD_NOT_MATCH: if it was because of a negative match (started with !)

tools ver_cmp(version1, version2)

Example:

tools.ver_cmp 3.2.1 3.3

Return Value
  • TOOLS_VERCMP_EQUAL: if the versions are the same
  • TOOLS_VERCMP_GT: if version1 > version2
  • TOOLS_VERCMP_LT: if version1 < version2
Parameters
  • version1: String with the first version to compare (must be in the form X.Y(.Z)? where X, Y and Z are numbers)
  • version2: String with the second version to compare (must be in the form X.Y(.Z)? where X, Y and Z are numbers)

dir /home/docs/checkouts/readthedocs.org/user_builds/ovirt-gerrit-hooks/checkouts/latest/hooks
dir /home/docs/checkouts/readthedocs.org/user_builds/ovirt-gerrit-hooks/checkouts/latest/hooks/lib