hadoop/dev-support/docs/precommit-architecture.md

Some Philosophy

• Everyone's time is valuable. The quicker contributors can get feedback and iterate, the more likely their contribution will get checked in. A committer should be able to focus on the core issues of a contribution rather than details that might be able to be determined automatically.

• Precommit 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, which is where integration tests should happen.

• Many open source projects have a desire to have this capability. Why not generalize a solution?

• In many build systems (especially with maven), a modular design has been picked. Why not leverage that design to make checks faster?

• Projects that use the same language will, with a high degree of certainity, benefit from the same types of checks.

• Portability matters.

Phases

test-patch works effectively under several different phases:

Setup

This is where test-patch configures and validates the environemnt. Some things done in this phase:

• Defaults
• Parameter handling
• Importing plugins and personalities
• Docker container launching
• Re-exec support
• Patch file downloading
• git repository management (fresh pull, branch switching, etc)

Post-checkout

Checks done here are fatal.

This acts as a verification of all of the setup parts and is the final place to short-cut the full test cycle. The most significant built-in check done here is verifying the patch file is a valid.

Pre-apply

This is where the 'before' work is handled. Some things done in this phase:

• The first pass of files and modules that will get patched
• Validation and information gathering of java, javadoc, site, the mvn repo, findbugs, etc.
• Author checks
• check for modified unit tests

Patch is Applied

The patch gets applied. Then a second pass to determine which modules and files have been changed in order to handle any modules that might have added or moved.

Post-apply

Now that the patch has been applied, many of the same checks performed in the Pre-apply step are done again to build an 'after' picture.

• Validation and information gathering of java, javadoc, site, the mvn repo, findbugs, etc.

Post-install

Some tests only work correctly when the repo is up-to-date. So mvn install is run to update the local repo and we enter this phase. Tests performed here:

• Verification that maven eclipse integration still works
• FindBugs

Unit Tests

Since unit tests are generally the slowest part of the precommit process, they are run last. At this point, all the prerequisites to running them should be in place and ready to go.

Reporting

Finally, the results are reported to the screen and, optionally, to JIRA.

Test Flow

The basic workflow for many of the sub-items in individual phases are:

1. print a header, so the end user knows that something is happening
2. verify if the test is needed. If so, continue on. Otherwise, return success and let the next part of the phase execute.
3. Ask the personality about what modules and what flags should get used
4. Execute maven in the given modules with the given flags. Log the output and record the time and result code.
5. Do any extra work as appropriate (diffs, counts, etc) and either accept the status and message given by the maven run or change the vote, message, log file, etc.
6. Add the outcome(s) to the report generator

As one can see, the modules list is one of the key inputs into what actually gets executed. As a result, projects must full flexibility in either adding, modifying, or even removing modules from the test list. If a personality removes the entire list of modules, then that test should just be ignored.