Skip to content

index.html.md

Latest commit

 

History

History
183 lines (140 loc) · 7.3 KB

index.html.md

File metadata and controls

183 lines (140 loc) · 7.3 KB

Basic Precommit

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:

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:

Automation and Isolation:

Unit Test Formats:

Compiler Support:

Commonly Parsed File Formats:

Language Support, Licensing, and more:

Related Utilities

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

More information