# Basic Precommit

- Purpose
- Goals
- Pre-requisites
  - Base Requirements
  - Plug-ins
    - Bundled Plug-ins
    - Optional Plug-ins
- Related Utilities
- More information

# Purpose

Performing reviews can be an overwhelming process. The more complex the base, the more comprehensive reviews end up. Building that functionality into the build itself is a full time job. When a new check is added there is a good chance the existing code has problems and often maintainers just want to prevent new bits from making the existing problem worse.

This is where Apache Yetus' precommit utilities come into the picture.

All patches to the source base go through a test that does some (relatively) light checking to make sure the proposed change does not break unit tests and/or passes some other prerequisites such as code formatting guidelines. This is meant as a preliminary check for reviewers so that the basic patch is in a known state and for contributors to know if they have followed the project's guidelines. This check may also be used by individual developers to verify a patch prior to sending to the QA systems.

# Goals

- Everyone's time is valuable. The quicker contributors can get feedback and iterate, the more likely and faster their contribution will get checked in. A committer should be able to focus on the core issues of a contribution rather than details that can be determined automatically.
- Checks should be fast. There is no value in testing parts of the source tree that are not immediately impacted by a change. Unit testing is the target. They are not a replacement for full builds or integration tests.
- In many build systems (e.g., maven), a modular design has been picked. This modularity should be exploited to reduce the amount of checks that need to be performed.
- Projects that use the same language will, with a high degree of certainty, benefit from the same types of checks.
- Portability matters. Tooling should be as operating system and language agnostic as possible.

# Pre-requisites

Almost all of the precommit components are written in bash for maximum portability. As such, it mostly assumes the locations of commands to be in the file path. However, in many cases, this assumption may be overridden via command line options.

## Base Requirements

These components are expected to be in-place for basic execution:

- git-based project (and git 1.7.3 or higher installed)
- bash v3.2 or higher (bash v4.0 or higher is recommended)
- GNU diff
- GNU patch
- POSIX awk
- POSIX grep
- POSIX sed
- curl command
- file command

For Solaris and Solaris-like operating systems, the default location for the POSIX binaries is in `/usr/xpg4/bin` and the default location for the GNU binaries is `/usr/gnu/bin`.

## Plug-ins

Features are plug-in based and enabled either individually or collectively on the command line. From there, these are activated based upon tool availability, the languages being tested, etc. The external dependencies of plug-ins may have different licensing requirements than Apache Yetus.

### Bundled Plug-ins

These plug-ins are native to Apace Yetus and are (usually!) always available:

- author
- blanks
- briefreport
- dupname
- htmlout
- nobuild
- pathlen
- slack
- unitveto
- xml

### Optional Plug-ins

Bug Systems:

- Bugzilla-based issue tracking (Read Only)
- GitHub-based issue tracking
- Gitlab-based issue tracking
- JIRA-based issue tracking

Build Tools:

- ant
- autoconf
- cmake
- gradle
- maven
- make

Automation and Isolation:

- Azure Pipelines
- Buildkite
- Circle CI
- Cirrus CI
- Docker version 1.7.0+
- Github Actions
- Gitlab CI
- Jenkins
- Semaphore CI
- Travis CI

Unit Test Formats:

- ctest
- JUnit, as input and output
- TAP

Compiler Support:

- C/C++
- Go
- Java, both javac and javadoc
- Scala, both scalac and scaladoc

Language Support, Licensing, and more:

- Apache Creadur Rat
- buf
- checkmake
- checkstyle
- FindBugs
- golangci-lint
- hadolint
- jshint
- markdownlint-cli
- Perl::Critic
- pylint
- revive
- rubocop
- shellcheck
- SpotBugs
- yamllint

# Related Utilities

`precommit` also comes with some utilities that are useful in various
capacities without needing to use the full `test-patch` runtime:

- docker-cleanup - safe removal of Docker resources for multi-executor CI systems
- github-status-recovery - Apache Yetus status on GitHub, even for long running jobs
- jenkins-admin - Jenkins<->JIRA patch bridge
- qbt - Quality Build Tool, for branch-specific testing
- smart-apply-patch - CLI manipulation and query of patch files, PRs, and more

# More information

- Usage Introduction
- Advanced Usage Guide
- Internal Architecture
- Various Subsystems:
  - build systems
  - bug systems
  - continuous integration system support
  - test formats
- Detailed Docker information
- Generated API documentation
- Glossary