tools/review-tools

Requirements
============

For the scripts below to work properly, the following must be installed:

* OpenSSL-Query: Follow the instructions in its README.md

Optionally, OMC members can benefit from direct database access by installing
the QueryApp libraries (found in the OMC tools repository) as well.

Environment
===========

Some of the scripts use the information REST API on https://api.openssl.org
while ghmerge also uses https://api.github.com.
The environment variables 'https_proxy' and 'no_proxy' can be used.

If you have direct access to the databases and want to use that instead, set
the environment variable OMC to the directory where they are located.

The scripts
===========

addrev
------

addrev and gitaddrev is a simple pair of scripts to add or edit reviewers to
commits.

To use add the scripts gitaddrev and addrev to your PATH.

Run 'addrev --help' for usage.

If a reviewer already exists in the log message, it isn't added again.

If the committer is not the author of the commit then they are added
automatically as a reviewer.

Reviewer names can be given as simple known lower case names, or as github
IDs prefixed with a @, or known email addresses if given with --reviewer.

Run 'addrev --list' to ge a list of known reviewer names.

The tool accesses databases on api.openssl.org.
The environment variables 'https_proxy' and 'no_proxy' can be used.
The transfer may take many seconds, in particular with the '--list' option.

Examples:

    addrev --prnum=1234 steve
    addrev 1234 -2 steve
    addrev 1234 -2 steve @richsalz
    addrev 1234 -2 --reviewer=steve --reviewer=rsalz@openssl.org

gitlabutil
----------

NOTE: Only useful for OMC members

gitlabutil is a simple gitlab merge request query tool.

Before you can use it you need to create a file $HOME/.gitlabtoken containing
your gitlab token (see profile).

Usage is:

	gitlabutil [options]

By default it prints out a summary of all open merge requests. This
behaviour can be changed with various command line options.

--state indicates the state of the requests to query, it can be "all",
"merged", "opened" or "closed". By default only openened requests are searched.

--token indicates the private token to use (see Account Settings in your
profile). If not specified it will look for a token in $HOME/.gitlabtoken
It is a fatal error if a token is not supplied.

--desc indicates a regular expression which must match the request description

--user only print requests with the given user name.

[number] an optional number of the merge request (iid value as indicated in
the UI).

--text print the full description of the request.

--fetch create branch from matching request using same branch name as in the
request: there must only be a single match for this to work.

--checkout is like --fetch but also changes the current branch to the name on
the merge request.

Examples.

Get summary of merge request 1

	gitlabutil --state=all 1

Get full details of all requests made by user "foo":

	gitlabutil --state=all --user=foo --text

Checkout branch for query 145:

	gitlabutil --checkout 145

ghmerge
-------

ghmerge calls addrev and pushes (reviewed and approved!) GitHub pull requests.
It includes several safety precautions and questions such as showing the diff,
showing the resulting commit messages, and (by default) rebuilding everything.

It works on the current branch, which should be 'master' or one of the stable
releases. The default remote is the first one matching
'github.openssl.org:(openssl|omc|otc).*(push)'. So typically before calling
'ghmerge' one would have done the following:

	git remote -v
origin	openssl-git@github.openssl.org:openssl/openssl.git (fetch)
origin	openssl-git@github.openssl.org:openssl/openssl.git (push)
	git fetch origin
	git checkout master

The tool accesses external databases on api.openssl.org and api.github.com.
The environment variables 'https_proxy' and 'no_proxy' can be used.

Example usage patterns:
        ghmerge <prnum> <reviewers>...
        ghmerge --tools --squash <prnum> <reviewer>...

The default commit post-processing operaton is 'git rebase -i --autosquash'.

Available options are:

--noautosquash  Use default interactive post-processing but without '--autosquash'.
--squash        Use non-interactive post-processing 'git merge --ff-only --squash'.
--nobuild       Do not use 'opensslbuild'.
                Else it is invoked with $CC defaulting to "ccache gcc".
--remote        Select the git remote of the branch to pull from and push to.
                Default is the first remote matching 'git.openssl.org.*(push)'.
--tools         Select the 'tools' repository rather than 'openssl'.
                This implies '--nobuild'.
--web           Select the 'web' repository rather than 'openssl'.
                This implies '--nobuild'.
--trivial       Pass '--trivial' to the invocation of 'addrev'.

The <prnum> is the GitHub PR number.  The rest of the args are the names
of the reviewers. All this info will be passed to addrev; see above.


pick-to-branch
--------------

pick-to-branch cherry-picks commits to branches