saintstack commented on a change in pull request #1392: HBASE-24081 Provide documentation for running Yetus with HBase URL: https://github.com/apache/hbase/pull/1392#discussion_r400493635
########## File path: dev-support/HOW_TO_YETUS_LOCAL.md ########## @@ -0,0 +1,166 @@ +# How To Use Apache Yetus with Apache HBase + +This document describes how to get up and running with [Apache Yetus][yetus], +as pertains to development of Apache HBase. Specifically this covers the use +of `test-patch`, of which HBase developers make use for tasks related to code +quality. These are normally run via automation in the foundation's +[Build][builds] infrastructure. They can also be run locally, which is the +subject this document. + +The Yetus project provides it's own documentation of `test-patch` in +[Basic PreCommit][yetus-basic-precommit]. By comparison, this document is +intended to be highly abbreviated, hands-on, and focused on the HBase use-case. +See that document for more complete explanations and further details. + +## Installation + +In order to run Yetus, you'll need to first install Yetus and its dependencies. +This is somewhat simplified when used in Docker mode. Yetus can be retrieved +from a [distribution artifact][yetus-downloads]. Homebrew/Linuxbrew users can +install from the tap, the process for which is also described on the downloads +page. + +# Usage Basics + +Apache Yetus is comprised of a number of different components. The focus of our +interest is `test-patch`. `test-patch` is a modular system. Many modules depend +on some external tool to provide the underlying functionality. For example, the +`compile` check delegates to a number of provider modules, for example `maven` +or `gradle` for JVM projects. In order to use these modules, those tools must +be installed. Yetus calls these modules "plugins". + +To see a list of all plugins available to `test-patch`, use + +```shell script +$ test-patch --list-plugins +``` + +To see a list of all the options available in both the core modules as well as +all the plugins, use + +```shell script +$ test-patch --plugins=all --help +``` + +An invocation of `test-patch` requires use of one or more plugins. Often times, +when the full suite of checks are run, specify the meta-plugin "all". Otherwise, +a limited selection of plugins can be selected using the `--plugins` argument. + +## The Workspace, The Patch + +`test-patch` operates within a "workspace," a checkout from a source control +repository. It has a number of options pertaining to this workspace, such as +the path to the workspace (`--basedir`) and whether it will permit the presence +of uncommitted changes therein (`--dirty-workspace`). + +Onto this workspace, it can optionally apply a change, a.k.a., the "patch" in +"test patch." The patch can come from a number of sources, including a patch +file, a JIRA ID, a Pull Request, &c. Or, explicitly inform Yetus that no patch +file is provided, and the repository should be checked as is, by passing +`--empty-patch`. + +## Personalities + +`test-patch` is extremely extensible. Even the functionality of its core +modules can be extended or overridden. It allows for this type of +"personalization" by way of "personality" override. Yetus ships a number of +these personalities; a pre-packaged personality can be selected via the +`--project` parameter. There is a provided HBase personality in Yetus, however +the HBase project maintains its own within the HBase source repository. Specify +the path to the personality file using `--personality`. The HBase repository +places this file under `dev-support/hbase-personality.sh`. + +## Docker mode + +Running Yetus in Docker mode simplifies the concerns of dependencies because +the provided `Dockerfile` handles their installation automatically. However, +for MacOS users, there are a number of known issues with running Docker on OSX, +so it may be preferable to instead run outside of the container. + +To run in Docker, of course you must install `docker` or some container runtime +equivalent. [Docker Desktop][docker-desktop] is an option for Mac and Windows +users. + +When running `test-patch` with HBase in docker mode, two parameters must be +provided. `--docker` activates the `docker` module, enabling the feature. +Additionally, `--dockerfile` points Yetus as HBase's provided `Dockerfile`, Review comment: s/as/at/ ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
