diff --git a/.circleci/config.yml b/.circleci/config.yml index 08798682f..c55bd5d3b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -19,15 +19,14 @@ version: 2 jobs: build: docker: - - image: ghcr.io/apache/yetus:main + - image: ghcr.io/effectivemachines/buretoolbox:main working_directory: ~/repo environment: # Customize the JVM maximum heap limit MAVEN_OPTS: -Xmx3200m - # Set JAVA_HOME - JAVA_HOME: /usr/lib/jvm/java-8-openjdk-amd64 + JAVA_HOME: /usr/lib/jvm/default-java steps: - checkout @@ -38,7 +37,6 @@ jobs: - run: > ~/repo/precommit/src/main/shell/test-patch.sh --plugins=all - --java-home=/usr/lib/jvm/java-11-openjdk-amd64 --patch-dir=/tmp/yetus-out --html-report-file=/tmp/yetus-out/report.html --console-report-file=/tmp/yetus-out/console.txt diff --git a/.cirrus.yml b/.cirrus.yml index 086c27440..fe8875930 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -17,7 +17,9 @@ yetus_task: container: - image: ghcr.io/apache/yetus:main + image: ghcr.io/effectivemachines/buretoolbox:main + env: + JAVA_HOME: /usr/lib/jvm/default-java test_script: > ${CIRRUS_WORKING_DIR}/precommit/src/main/shell/test-patch.sh --basedir="${CIRRUS_WORKING_DIR}" @@ -26,7 +28,6 @@ yetus_task: --console-report-file=/tmp/yetus-out/console.txt --csv-report-file=/tmp/yetus-out/report.csv --html-report-file=/tmp/yetus-out/report.html - --java-home=/usr/lib/jvm/java-11-openjdk-amd64 --junit-report-xml=/tmp/yetus-out/junit.xml --plugins=all --junit-report-xml=line diff --git a/.github/workflows/action-test.yml b/.github/workflows/action-test.yml index 154683f2a..cc49dd7da 100644 --- a/.github/workflows/action-test.yml +++ b/.github/workflows/action-test.yml @@ -38,7 +38,6 @@ jobs: uses: apache/yetus-test-patch-action@main with: basedir: ./src - javahome: /usr/lib/jvm/java-11-openjdk-amd64 patchdir: ./out buildtool: maven githubtoken: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/yetus.yml b/.github/workflows/yetus.yml index d8eef4039..d35ca16ad 100644 --- a/.github/workflows/yetus.yml +++ b/.github/workflows/yetus.yml @@ -48,10 +48,9 @@ jobs: --console-report-file="${GITHUB_WORKSPACE}/out/console.txt" --csv-report-file="${GITHUB_WORKSPACE}/out/report.csv" --docker - --docker-cache-from=ghcr.io/apache/yetus-base:main + --docker-cache-from=ghcr.io/effectivemachines/buretoolbox:main --github-token="${{ secrets.GITHUB_TOKEN }}" --html-report-file="${GITHUB_WORKSPACE}/out/report.html" - --java-home=/usr/lib/jvm/java-11-openjdk-amd64 --junit-report-xml="${GITHUB_WORKSPACE}/out/junit-report.xml" --patch-dir="${GITHUB_WORKSPACE}/out" --plugins=all diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index eae1a60ca..8df6d27fc 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -16,14 +16,15 @@ --- buretoolbox-job: - image: ghcr.io/apache/yetus:main + image: ghcr.io/effectivemachines/buretoolbox:main allow_failure: true + variables: + JAVA_HOME: /usr/lib/jvm/default-java script: - > precommit/src/main/shell/test-patch.sh --patch-dir=/tmp/yetus-out --plugins=all - --java-home=/usr/lib/jvm/java-11-openjdk-amd64 --html-report-file=/tmp/yetus-out/report.html --csv-report-file=/tmp/yetus-out/report.csv --console-report-file=/tmp/yetus-out/console.txt diff --git a/.travis.yml b/.travis.yml index b923a8345..65cb8c549 100644 --- a/.travis.yml +++ b/.travis.yml @@ -30,9 +30,8 @@ script: precommit/src/main/shell/test-patch.sh --docker --patch-dir=/tmp/yetus-out - --java-home=/usr/lib/jvm/java-11-openjdk-amd64 --plugins=all,-detsecrets - --docker-cache-from=ghcr.io/apache/yetus:main + --docker-cache-from=ghcr.io/effectivemachines/buretoolbox:main --html-report-file=/tmp/yetus-out/report.html --console-report-file=/tmp/yetus-out/console.txt --brief-report-file=/tmp/yetus-out/brief.txt diff --git a/Jenkinsfile b/Jenkinsfile index 2bc9da6c1..af2268db8 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -95,7 +95,6 @@ pipeline { # enable writing back to Github YETUS_ARGS+=(--github-token="${GITHUB_TOKEN}") - YETUS_ARGS+=(--java-home=/usr/lib/jvm/java-11-openjdk-amd64) # enable writing back to ASF JIRA YETUS_ARGS+=(--jira-issue-re='^YETUS-[0-9]*$') @@ -133,10 +132,10 @@ pipeline { # run in docker mode and specifically point to our # Dockerfile since we don't want to use the auto-pulled version. if [[ "${USE_DOCKER_FLAG}" == true ]]; then - docker pull ubuntu:jammy + docker pull ubuntu:noble YETUS_ARGS+=("--docker") YETUS_ARGS+=("--dockerfile=${YETUS_DOCKERFILE}") - YETUS_ARGS+=("--docker-cache-from=ghcr.io/apache/yetus-base:main") + YETUS_ARGS+=("--docker-cache-from=ghcr.io/effectivemachines/buretoolbox:main") else # need to figure this out programmatically; hard-coded for now export JAVA_HOME=/home/jenkins/tools/java/latest1.8 diff --git a/asf-site-src/Dockerfile b/asf-site-src/Dockerfile index c67e367ef..c277f1e96 100644 --- a/asf-site-src/Dockerfile +++ b/asf-site-src/Dockerfile @@ -48,7 +48,7 @@ RUN apt-get -q update \ RUN echo "export GPG_TTY=\$(tty)" >> /root/.bashrc # hadolint disable=DL3059 RUN groupadd --non-unique -g "${GROUP_ID}" "${USER_NAME}" \ - && useradd -l -g "${GROUP_ID}" -u "${USER_ID}" -k /root -m "${USER_NAME}" + && useradd --non-unique -l -g "${GROUP_ID}" -u "${USER_ID}" -k /root -m "${USER_NAME}" # hadolint disable=DL3059,SC2039,SC1117 RUN echo -e "${USER_NAME}\\tALL=NOPASSWD: ALL" > "/etc/sudoers.d/yetus-build-${USER_ID}" # pragma: allowlist secret ENV HOME=/home/${USER_NAME} @@ -79,10 +79,9 @@ ENV GEM_HOME=${BUNDLE_PATH} # pre-install most of the middleman stack to save time # on re-launches # hadolint ignore=DL3028 -RUN gem install bundler \ - middleman:'4.5.0' \ +RUN gem install bundler:'4.0.8' \ + middleman:'4.6.3' \ middleman-syntax \ - nokogiri:1.15.4 \ sassc:2.4.0 \ tzinfo-data diff --git a/asf-site-src/Gemfile.lock b/asf-site-src/Gemfile.lock index 6568ecfd5..0cc863df7 100644 --- a/asf-site-src/Gemfile.lock +++ b/asf-site-src/Gemfile.lock @@ -1,128 +1,153 @@ GIT remote: https://github.com/middleman/middleman-syntax.git - revision: 2d44853d28766850db2ca800e880270fa7dd8ad6 + revision: 89aab5386c40bb99cfe670396e53c334d7ea3460 specs: - middleman-syntax (3.4.0) + middleman-syntax (3.6.1) middleman-core (>= 3.2) - rouge (~> 3.2) + rouge (>= 3.2, < 5) GEM remote: https://rubygems.org/ specs: - activesupport (7.0.8.7) - concurrent-ruby (~> 1.0, >= 1.0.2) + activesupport (8.1.3) + base64 + bigdecimal + concurrent-ruby (~> 1.0, >= 1.3.1) + connection_pool (>= 2.2.5) + drb i18n (>= 1.6, < 2) + json + logger (>= 1.4.2) minitest (>= 5.1) - tzinfo (~> 2.0) - addressable (2.8.7) - public_suffix (>= 2.0.2, < 7.0) - backports (3.25.0) + securerandom (>= 0.3) + tzinfo (~> 2.0, >= 2.0.5) + uri (>= 0.13.1) + addressable (2.8.9) + public_suffix (>= 2.0.2, < 8.0) + base64 (0.3.0) + bigdecimal (4.1.0) coffee-script (2.4.1) coffee-script-source execjs coffee-script-source (1.12.2) - concurrent-ruby (1.3.4) - contracts (0.16.1) - dotenv (3.1.7) + concurrent-ruby (1.3.6) + connection_pool (3.0.2) + contracts (0.17.3) + dotenv (3.2.0) + drb (2.2.3) em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) - erubis (2.7.0) + erubi (1.13.1) eventmachine (1.2.7) execjs (2.10.0) fast_blank (1.0.1) - fastimage (2.4.0) - ffi (1.17.1) + fastimage (2.4.1) + ffi (1.17.4-aarch64-linux-gnu) + ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x86_64-darwin) + ffi (1.17.4-x86_64-linux-gnu) haml (5.2.2) temple (>= 0.8.0) tilt hamster (3.0.0) concurrent-ruby (~> 1.0) - hashie (3.6.0) - http_parser.rb (0.8.0) - i18n (1.6.0) + hashie (5.1.0) + logger + http_parser.rb (0.8.1) + i18n (1.14.8) concurrent-ruby (~> 1.0) - kramdown (2.5.1) - rexml (>= 3.3.9) + json (2.19.3) + kramdown (2.5.2) + rexml (>= 3.4.4) kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) - libv8-node (21.7.2.0-aarch64-linux) - libv8-node (21.7.2.0-arm64-darwin) - libv8-node (21.7.2.0-x86_64-darwin) - libv8-node (21.7.2.0-x86_64-linux) - listen (3.9.0) + libv8-node (24.12.0.1-aarch64-linux) + libv8-node (24.12.0.1-arm64-darwin) + libv8-node (24.12.0.1-x86_64-darwin) + libv8-node (24.12.0.1-x86_64-linux) + listen (3.10.0) + logger rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) memoist (0.16.2) - middleman (4.5.1) - coffee-script (~> 2.2) - haml (>= 4.0.5) - kramdown (>= 2.3.0) - middleman-cli (= 4.5.1) - middleman-core (= 4.5.1) - middleman-cli (4.5.1) - thor (>= 0.17.0, < 1.3.0) - middleman-core (4.5.1) - activesupport (>= 6.1, < 7.1) + middleman (4.6.3) + middleman-cli (= 4.6.3) + middleman-core (= 4.6.3) + middleman-cli (4.6.3) + thor (>= 0.17.0, < 2) + middleman-core (4.6.3) + activesupport (>= 6.1) addressable (~> 2.4) - backports (~> 3.6) - bundler (~> 2.0) - contracts (~> 0.13, < 0.17) + bundler (> 2.0) + coffee-script (~> 2.2) + contracts dotenv - erubis + erubi execjs (~> 2.0) fast_blank fastimage (~> 2.0) + haml (>= 4.0.5, < 7) hamster (~> 3.0) - hashie (~> 3.4) - i18n (~> 1.6.0) + hashie (>= 3.4, < 6.0) + i18n (>= 1.6, < 1.15) + kramdown (~> 2.4) listen (~> 3.0) memoist (~> 0.14) - padrino-helpers (~> 0.15.0) + padrino-helpers (>= 0.15, < 0.17) parallel - rack (>= 1.4.5, < 3) + rack (>= 3) + rackup sassc (~> 2.0) servolux - tilt (~> 2.0.9) + tilt (~> 2.2) toml - uglifier (~> 3.0) + uglifier (>= 3, < 5) webrick - middleman-livereload (3.4.7) + middleman-livereload (3.5.0) em-websocket (~> 0.5.1) middleman-core (>= 3.3) - rack-livereload (~> 0.3.15) - mini_racer (0.12.0) - libv8-node (~> 21.7.2.0) - minitest (5.25.4) - padrino-helpers (0.15.3) + rack-livereload (~> 0.6.1) + mini_racer (0.20.0) + libv8-node (~> 24.12.0.1) + minitest (6.0.2) + drb (~> 2.0) + prism (~> 1.5) + padrino-helpers (0.16.1) i18n (>= 0.6.7, < 2) - padrino-support (= 0.15.3) - tilt (>= 1.4.1, < 3) - padrino-support (0.15.3) - parallel (1.26.3) + padrino-support (= 0.16.1) + tilt (>= 2.1, < 3) + padrino-support (0.16.1) + parallel (1.27.0) parslet (2.0.0) - public_suffix (6.0.1) - rack (2.2.22) - rack-livereload (0.3.17) - rack + prism (1.9.0) + public_suffix (7.0.5) + rack (3.1.20) + rack-livereload (0.6.1) + rack (>= 3.0, < 3.2) + rackup (2.3.1) + rack (>= 3) rb-fsevent (0.11.2) rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.4.2) - rouge (3.30.0) + rexml (3.4.4) + rouge (4.7.0) sassc (2.4.0) ffi (~> 1.9) + securerandom (0.4.1) servolux (0.13.0) - temple (0.10.3) - thor (1.2.2) - tilt (2.0.11) + temple (0.10.4) + thor (1.5.0) + tilt (2.7.0) toml (0.3.0) parslet (>= 1.8.0, < 3.0.0) tzinfo (2.0.6) concurrent-ruby (~> 1.0) - uglifier (3.2.0) + uglifier (4.2.1) execjs (>= 0.3.0, < 3) - webrick (1.9.1) + uri (1.1.1) + webrick (1.9.2) PLATFORMS aarch64-linux @@ -141,4 +166,4 @@ DEPENDENCIES wdm (~> 0.1.0) BUNDLED WITH - 2.5.23 + 4.0.8 diff --git a/asf-site-src/config.rb b/asf-site-src/config.rb index 646d80ce0..4c9e08797 100644 --- a/asf-site-src/config.rb +++ b/asf-site-src/config.rb @@ -17,7 +17,6 @@ # limitations under the License. # -require 'ruby27_fix_uri' require 'kramdown-parser-gfm' set :markdown_engine, :kramdown diff --git a/asf-site-src/ruby27_fix_uri.rb b/asf-site-src/ruby27_fix_uri.rb deleted file mode 100644 index 6d4ab45fd..000000000 --- a/asf-site-src/ruby27_fix_uri.rb +++ /dev/null @@ -1,130 +0,0 @@ -# frozen_string_literal: true - -# -# Licensed to the Apache Software Foundation (ASF) under one or more -# contributor license agreements. See the NOTICE file distributed with -# this work for additional information regarding copyright ownership. -# The ASF licenses this file to You under the Apache License, Version 2.0 -# (the "License"); you may not use this file except in compliance with -# the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# - -# TODO: keep this only until this is fixed https://github.com/middleman/middleman/issues/2312 - -require 'webrick' -require 'middleman-core/builder' - -Middleman::Util.module_eval do - module_function - - def normalize_path(path) - return path unless path.is_a?(String) - - # The tr call works around a bug in Ruby's Unicode handling - WEBrick::HTTPUtils.unescape(path).sub(%r{^/}, '').tr('', '') - end -end - -Middleman::Rack.class_eval do - # https://github.com/middleman/middleman/blob/master/middleman-core/lib/middleman-core/rack.rb#L90 - def process_request(env, req, res) # rubocop:disable Metrics/AbcSize - start_time = Time.now - - request_path = WEBrick::HTTPUtils.unescape(env['PATH_INFO'].dup) - request_path.force_encoding('UTF-8') if request_path.respond_to? :force_encoding - request_path = ::Middleman::Util.full_path(request_path, @middleman) - full_request_path = File.join(env['SCRIPT_NAME'], request_path) # Path including rack mount - - # Run before callbacks - @middleman.execute_callbacks(:before) - - # Get the resource object for this path - resource = @middleman.sitemap.find_resource_by_destination_path(request_path.gsub(' ', '%20')) - - # Return 404 if not in sitemap - return not_found(res, full_request_path) unless resource && !resource.ignored? - - # If this path is a binary file, send it immediately - return send_file(resource, env) if resource.binary? - - res['Content-Type'] = resource.content_type || 'text/plain' - - begin - # Write out the contents of the page - res.write resource.render({}, rack: { request: req }) - - # Valid content is a 200 status - res.status = 200 - rescue Middleman::TemplateRenderer::TemplateNotFound => e - res.write "Error: #{e.message}" - res.status = 500 - end - - # End the request - logger.debug "== Finishing Request: #{resource.destination_path} (#{(Time.now - start_time).round(2)}s)" # rubocop:disable Layout/LineLength - halt res.finish - end -end - -Middleman::Builder.class_eval do - def output_resource(resource) # rubocop:disable Metrics/AbcSize - ::Middleman::Util.instrument 'builder.output.resource', path: File.basename(resource.destination_path) do # rubocop:disable Layout/LineLength - output_file = @build_dir + resource.destination_path.gsub('%20', ' ') - - begin - if resource.binary? - export_file!(output_file, resource.file_descriptor[:full_path]) - else - response = @rack.get(::URI.encode_www_form_component(resource.request_path)) - - # If we get a response, save it to a tempfile. - if response.status == 200 - export_file!(output_file, binary_encode(response.body)) - else - trigger(:error, output_file, response.body) - return false - end - end - rescue StandardError => e - trigger(:error, output_file, "#{e}\n#{e.backtrace.join("\n")}") - return false - end - - output_file - end - end -end - -Middleman::Extensions::AssetHash.class_eval do - def manipulate_single_resource(resource) # rubocop:disable Metrics/AbcSize - return unless @exts.include?(resource.ext) - return if ignored_resource?(resource) - return if resource.ignored? - - digest = if resource.binary? - ::Digest::SHA1.file(resource.source_file).hexdigest[0..7] - else - # Render through the Rack interface so middleware and mounted apps get a shot - response = @rack_client.get( - ::URI.encode_www_form_component(resource.destination_path), - 'bypass_inline_url_rewriter_asset_hash' => 'true' - ) - - raise "#{resource.path} should be in the sitemap!" unless response.status == 200 - - ::Digest::SHA1.hexdigest(response.body)[0..7] - end - - path, basename, extension = split_path(resource.destination_path) - resource.destination_path = options.rename_proc.call(path, basename, digest, extension, options) - resource - end -end diff --git a/asf-site-src/source/contribute/releases.html.md b/asf-site-src/source/contribute/releases.html.md index 92d1533c6..012dd3d65 100644 --- a/asf-site-src/source/contribute/releases.html.md +++ b/asf-site-src/source/contribute/releases.html.md @@ -151,7 +151,7 @@ the changelog and release notes. These files are part of our distribution and i are incorrect, will require a new RC. Therefore, before cutting a new release, make sure they do not have errors or missing information. The easiest way to do this check is to run through the [website](../website) directions to update the live website. After doing -that work, they should be listed [here](/downloads/releasenotes/) as the top entry. +that work, they should be listed on the [release notes page](/downloads/releasenotes/) as the top entry. ## Release Candidate(s) diff --git a/asf-site-src/source/documentation/history.html.md b/asf-site-src/source/documentation/history.html.md index d445810ca..b7caa4cb0 100644 --- a/asf-site-src/source/documentation/history.html.md +++ b/asf-site-src/source/documentation/history.html.md @@ -45,7 +45,7 @@ were equally useful and in some cases followed a similar path should also be cop the Apache Yetus repository. When it came time to split from Apache Hadoop, the `audience-annotations`, `releasedocmaker`, and `shelldocs` portions were also copied over. -# Old Source +## Old Source Due to coming from Apache Hadoop, the source repository history is extremely messy. The project underwent many major changes that make following changes much more difficult, diff --git a/asf-site-src/source/documentation/in-progress.html.md b/asf-site-src/source/documentation/in-progress.html.md index b4466755e..1a625e5f9 100644 --- a/asf-site-src/source/documentation/in-progress.html.md +++ b/asf-site-src/source/documentation/in-progress.html.md @@ -21,24 +21,24 @@ The [Yetus Precommit build, patch, and CI suite](precommit) allows projects to codify their patch acceptance criteria and then evaluate incoming contributions prior to review by a committer. -# Yetus Release Doc Maker +## Yetus Release Doc Maker The Release Documentation Maker allows projects to generate nicely formatted Markdown Changelogs and Release Notes based upon JIRA. You can view that -documentation [here](releasedocmaker). +[Release Doc Maker documentation](releasedocmaker). -# Yetus Shelldocs +## Yetus Shelldocs Shelldocs provides generation of html formatted api documentation based on comments on Bash functions. Currently supports documenting API status (public / private) as well as parameters and return values. See the [shelldocs page](shelldocs) for more information on usage. -# yetus-maven-plugin +## yetus-maven-plugin The [yetus-maven-plugin documentation](yetus-maven-plugin/) provides useful utility functions that are missing from Maven. -# Javadocs: Yetus Audience Annotations and more +## Javadocs: Yetus Audience Annotations and more Audience Annotations allows you to use Java Annotations to denote which parts of your Java library is publicly consumable and which parts are reserved for a more restricted use. It also provides doclets and examples for generating javadocs limited by audience. -You can refer the user documentation [here](interface-classification). +You can refer to the [interface classification documentation](interface-classification). -All javadocs (including audience annotations) are located [here](javadocs/). +All javadocs (including audience annotations) are located in the [Javadocs section](javadocs/). diff --git a/asf-site-src/source/documentation/in-progress/interface-classification.html.md b/asf-site-src/source/documentation/in-progress/interface-classification.html.md index d6f1e3897..878ce15c2 100644 --- a/asf-site-src/source/documentation/in-progress/interface-classification.html.md +++ b/asf-site-src/source/documentation/in-progress/interface-classification.html.md @@ -31,7 +31,7 @@ -# Motivation +## Motivation The interface taxonomy classification provided by Apache Yetus annotations is for guidance to developers and users of interfaces. The classification guides a developer to declare the targeted audience or users of an interface and also its stability. @@ -41,7 +41,7 @@ The interface taxonomy classification provided by Apache Yetus annotations is fo hence accidental impact on users or other components or system. This is particularly useful in large systems with many developers who may not all have a shared state/history of the project. -# Interface Classification +## Interface Classification Yetus provides the following interface classification, derived from the [OpenSolaris taxonomy](https://web.archive.org/web/20061013114610/http://opensolaris.org/os/community/arc/policies/interface-taxonomy/) @@ -109,7 +109,7 @@ Examples of publicly visible interfaces that are unstable APIs that could potentially be removed in the future and should not be used. -# How are the Classifications Recorded +## How are the Classifications Recorded [//]: # (This section needs improvement. Refer YETUS-458) @@ -122,7 +122,7 @@ How should the classification be recorded for the annotated APIs? audience of the package in which they are contained. Hence it is useful to declare the audience of each Java package as public or private (along with the private audience variations). -# FAQ +## FAQ * Why aren't the Java scopes (private, package private and public) good enough? * Java's scoping is not very complete. One is often forced to make a class public in order for other internal components to use it. It does not have friends or sub-package-private like C++. diff --git a/asf-site-src/source/documentation/in-progress/precommit/admin.html.md b/asf-site-src/source/documentation/in-progress/precommit/admin.html.md index 2fe6e7a78..13b4fcc26 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/admin.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/admin.html.md @@ -46,7 +46,7 @@ Additionally, the URL of the Jenkins server is expected to be in the `JENKINS_UR The very first run of the job should be done with the `--initialize` parameter to create the first `patch_tested.txt` file. Otherwise, the job will fail because a previous version of it cannot be downloaded from previous runs. -# Project-Specifc Builds +## Project-Specifc Builds New builds are started via buildWithParameters call. Three parameters are added to the URL: @@ -70,7 +70,7 @@ The job name can be overridden via the `--jenkins-project-template` option. For .../job/PreCommit-YETUS-Build/buildwithParameters?... -# Jenkins Job Tokens +## Jenkins Job Tokens Currently, jenkins-admin supports the usage of Jenkins tokens for authentication via the `--jenkins-token` option. This option provides two ways to do tokens diff --git a/asf-site-src/source/documentation/in-progress/precommit/advanced.html.md b/asf-site-src/source/documentation/in-progress/precommit/advanced.html.md index 5257321a0..a7302b22b 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/advanced.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/advanced.html.md @@ -36,7 +36,7 @@ -# Process Reaper +## Process Reaper A common problem is the 'stuck' unit test. If bash v4.0 or higher is in use, Apache Yetus may be told to turn on the process reaper functionality. Using the `--reapearmode` option, this feature may be configured to either report and even kill left over processes that match provided regular expressions. @@ -44,7 +44,7 @@ A common problem is the 'stuck' unit test. If bash v4.0 or higher is in use, Apa The reaper will run after every 'external' command that is printed on the console. This includes almost all build tool commands and individual test commands. -# Plug-ins +## Plug-ins test-patch allows one to add to its basic feature set via plug-ins. There is a directory called plugins.d inside the directory where test-patch.sh lives. Inside this directory one may place some bash shell fragments that, if setup with proper functions, will allow for test-patch to call it as necessary. Different plug-ins have specific functions for that particular functionality. In this document, the common functions available to all/most plug-ins are covered. Test plugins are covered below. See other documentation for pertinent information for the other plug-in types. @@ -140,7 +140,7 @@ add_test_type NOTE: If the plug-in has support for maven, the maven_add_install `pluginname` should be executed. See more information in Custom Maven Tests in the build tool documentation. -# Personalities +## Personalities It is impossible for any general framework to be predictive about what types of special rules any given project may have, especially when it comes to ordering and Maven profiles. In order to direct test-patch to do the correct action, a project `personality` should be added that enacts these custom rules. @@ -262,7 +262,7 @@ personality_plugins "all,-checkstyle,-spotbugs,-asflicense" This list is used if the user does not provide a list of plug-ins. -# Important Variables +## Important Variables There are a handful of extremely important system variables that make life easier for personality and plug-in writers. Other variables may be provided by individual plug-ins. Check their development documentation for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/architecture.html.md b/asf-site-src/source/documentation/in-progress/precommit/architecture.html.md index de050618d..a2c164e7f 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/architecture.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/architecture.html.md @@ -106,7 +106,7 @@ in place and ready to go. Finally, the results are reported to the screen and, optionally, to JIRA and/or whatever bug system has been configured. -# Test Flow +## Test Flow The basic workflow for many of the sub-items in individual phases are: diff --git a/asf-site-src/source/documentation/in-progress/precommit/bugsystems.html.md b/asf-site-src/source/documentation/in-progress/precommit/bugsystems.html.md index d6c70e48d..411cbb7c3 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/bugsystems.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/bugsystems.html.md @@ -53,7 +53,7 @@ add_bugsystem * pluginname\_finalreport * Write the final result table to the bug system. -# Bugzilla Specific +## Bugzilla Specific Currently, Bugzilla support is read-only. To use it, the Bug ID must be preferenced with 'BZ:'. For example: @@ -65,7 +65,7 @@ $ test-patch (other options) BZ:4 Using the `--bugzilla-base-url` on the command line or BUGZILLA\_BASE\_URL in a project's personality will define the location of the Bugzilla instance. By default, it is . -# GitHub Specific +## GitHub Specific GitHub supports a large range of functionality, mostly self-adjusting based upon the environment it is running in. Supported features include GitHub Enterprise, private @@ -110,7 +110,7 @@ the appropriate documentation for your particular setup. The token is provided via the `--github-token` option. -# GitLab Specific +## GitLab Specific GitLab supports the full range of functionality, including putting comments on individual lines. Be aware, however, that `test-patch` will (generally) require that GitLab MRs be fully squashed and rebased (i.e., a single commit) in many circumstances. @@ -128,7 +128,7 @@ GitLab merge requests may be directly processed on the command line in two ways: The GitLab bugsystem plugin will attempt to download the unified diff that the merge request references. Merge requests that are made off of a specific branch will switch the test repo to that branch, if permitted. If the merge request references a JIRA issue that matches the given JIRA issue regexp in the Subject, the JIRA plug-in will also be invoked as needed. -# JIRA Specific +## JIRA Specific JIRA support allows both patch downloads and summary writes. It also supports branch detection-based upon the name of the attached patch file. diff --git a/asf-site-src/source/documentation/in-progress/precommit/buildtools.html.md b/asf-site-src/source/documentation/in-progress/precommit/buildtools.html.md index 0c8080fdd..280aca0a7 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/buildtools.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/buildtools.html.md @@ -61,7 +61,7 @@ test-patch has the ability to support multiple build tools and [personalities](. add_build_tool ``` -# Global Variables +## Global Variables ## BUILDTOOLCWD @@ -79,7 +79,7 @@ If pluginname\_modules\_worker is given a test type that is not supported by the For example, the gradle build tool does not have a standard way to execute checkstyle. So when checkstyle is requested, gradle\_modules\_worker sets UNSUPPORTED\_TEST to true and returns out of the routine. -# Required Functions +## Required Functions Note: In a personality, `pluginname` can be arbitrary. @@ -103,7 +103,7 @@ Default method to determine how to enqueue modules for processing. Note that pe Default method to determine which tests to trigger. Note that personalities may override this function. Requires a single argument: the file in which the tests exist. -# Optional Functions +## Optional Functions ## pluginname\_parse\_args @@ -138,7 +138,7 @@ If the build tool requires extra settings on the `docker run` command line (more **WARNING**: Be aware that directories that do not exist MAY be created by root by Docker itself under certain conditions. It is HIGHLY recommend that [`pluginname_initialize`](#pluginname\_initialize) be used to create the necessary directories prior to use in the `docker run` command. -# Apache Ant Specific +## Apache Ant Specific ## Ant Command Arguments @@ -148,7 +148,7 @@ test-patch always passes -noinput to Ant. This forces ant to be non-interactive In Docker mode, the `${HOME}/.ivy2` directory is shared amongst all invocations. -# autoconf Specific +## autoconf Specific autoconf requires make to be enabled. autoreconf is always used to rebuild the configure script. @@ -156,21 +156,21 @@ autoconf requires make to be enabled. autoreconf is always used to rebuild the autoconf will always run configure with prefix set to a directory in the patch processing directory. To configure other flags, set the AUTCONF_CONF_FLAGS environment variable. -# CMAKE Specific +## CMAKE Specific By default, cmake will create a 'build' directory and perform all work there. This may be changed either on the command line or via a personality setting. cmake requires make to be enabled. -# Gradle Specific +## Gradle Specific The gradle plug-in always rebuilds the gradlew file and uses gradlew as the method to execute commands. In Docker mode, the `${HOME}/.gradle` directory is shared amongst all invocations. -# Make Specific +## Make Specific No notes. -# Apache Maven Specific +## Apache Maven Specific ## Command Arguments diff --git a/asf-site-src/source/documentation/in-progress/precommit/docker-cleanup.html.md b/asf-site-src/source/documentation/in-progress/precommit/docker-cleanup.html.md index 59a5416e8..0387ec75b 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/docker-cleanup.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/docker-cleanup.html.md @@ -28,14 +28,14 @@ -# Description +## Description `docker-cleanup` is a command to perform precommit's Docker cleanup functionality outside of patch and build testing. It is designed to be run as a regularly automated job on CI systems that do not have their own Docker cleanup facilities. It is built from the perspective that nothing on the system is permanent. It supports many of the same options as `test-patch`'s [docker](../docker)-mode. Please see that page for more details. -# Usage +## Usage ## Default Mode diff --git a/asf-site-src/source/documentation/in-progress/precommit/docker.html.md b/asf-site-src/source/documentation/in-progress/precommit/docker.html.md index 9beb22f8e..74687d2c9 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/docker.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/docker.html.md @@ -41,13 +41,13 @@ -# The Basics +## The Basics By default, test-patch runs in the same shell where it was launched. It can alternatively use Docker to launch itself in a Linux container by using the `--docker` parameter. This is particularly useful if running under a QA environment that does not provide all the necessary binaries. For example, if the patch requires a newer version of Java than what is installed on a CI instance. Each run will spawn two Docker images, one that contains some sort of base image and one specific to each run. The base image is described further in this text. The run-specific image is a small one that passes parameters and settings that are dedicated to that run, with "tp-" as part of the Docker image tag. It should be removed automatically after the run upon test-patch completion. -# Docker Base Images +## Docker Base Images ## Default Image @@ -84,28 +84,28 @@ By default, precommit will use `/precommit` as the directory where it will store not provided by other flags in system (such as `--basedir` or `--patch-dir`). If that directory conflicts with some other need, then the `--docker-work-dir` option may be provided to set a different path. -# BuildKit +## BuildKit By default, precommit will enable [Docker BuildKit](https://docs.docker.com/develop/develop-images/build_enhancements/) unless told otherwise with `--docker-buildkit=false` or if the CI system has known limitations. -# Resource Controls +## Resource Controls Docker's `--memory` flag is supported via the `--dockermemlimit` option. This enables the container's memory size to be limited. This may be important to set to prevent things like broken unit tests bringing down the entire build server. See [the Docker documentation](https://docs.docker.com/engine/admin/resource_constraints/) for more details. Apache Yetus also sets the `--oom-score-adj` to 500 in order to offer itself as the first processes to be killed if memory is low. Additionally, if bash v4 and Linux is in use, a separate process is launched to keep a rolling count of the maximum number of threads (not processes!) in use at one time. This number will be reported at the end of the test-patch run. Depending upon the build, languages, features enabled, etc, this number may be helpful in determining what the value of `--proclimit` -# Privileged Mode +## Privileged Mode In some cases, the work being performed inside the Docker container requires extra permissions. Using the `--docker-privd` option enables Docker's extended privileges to the container. -# Docker in Docker +## Docker in Docker With the usage of the `--dockerind` flag, test-patch will mount the `/var/run/docker.sock` UNIX socket into the container to enable Docker-in-Docker mode. Additionally, the `--docker-socket` option will let one set the socket to mount in situations where that isn't the location of the socket, such as a dockerd proxy providing authentication. NOTE: Using --dockerind requires the availability of the `stat` command that supports either -c '%g' (GNU form) or -f '%g' (BSD form). -# Cleaning the Docker Environment +## Cleaning the Docker Environment With the growing use of Docker for CI purposes, so is the growing need to help manage the Docker environment. Stale, large caches and stuck containers are a common problem when tests go haywire. In order to help combat that, Apache Yetus includes @@ -119,11 +119,11 @@ However if the system is in [Robot](../robots)-mode or `--sentinel` is used, car For container images, there are three modes. Each mode increases the amount of coverage that Apache Yetus will use to remove images. -| Mode | Images Types | Time Frame | -|:----:|:------------:|:----------:| -| default | all | NA | -| `--robot` | dangling, label=org.apache.yetus | 1 week | -| `--sentinel` | all | 1 week | +| Mode | Images Types | Time Frame | +| :----------- | :------------------------------- | :--------- | +| default | all | NA | +| `--robot` | dangling, label=org.apache.yetus | 1 week | +| `--sentinel` | all | 1 week | Before it begins, Apache Yetus will show the contents of `docker images` so that there is a history of what was in the cache. This also helps determine what was deleted later. Next, it finds images that fall within the time frame of @@ -135,10 +135,10 @@ an idea of what is happening under the hood. For containers there are two modes: -| Mode | Images Types | Time Frame | -|:----:|:------------:|:----------:| -| default | all | NA | -| `--sentinel` | all | 24 hours | +| Mode | Images Types | Time Frame | +| :----------- | :----------- | :--------- | +| default | all | NA | +| `--sentinel` | all | 24 hours | Under just plain `--robot`, containers are left alone. Under `--sentinel`, containers (regardless of state) are killed after 24 hours. diff --git a/asf-site-src/source/documentation/in-progress/precommit/github-status-recovery.html.md b/asf-site-src/source/documentation/in-progress/precommit/github-status-recovery.html.md index 0cb6740d6..547b26800 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/github-status-recovery.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/github-status-recovery.html.md @@ -27,14 +27,14 @@ -# Problem Statement +## Problem Statement For CI systems that use GitHub outside of GitHub Actions, they may make available a GitHub Checks token. Unfortunately, as of this writing (2020-10-30), GitHub sets the expiry of such a token to 1 hour. For some users of Apache Yetus, their precommit job may take longer than one hour. In order to workaround this limitation, the `github-status-recovery` program may be used. -# Usage +## Usage The usage is relatively simple: @@ -45,6 +45,6 @@ $ github-status-recovery --patch-dir= --github-tok If the previous run of `test-patch` failed to write the status, `github-status-recovery` will re-process the saved JSON files as well as write GitHub Checks Annotations if they exist. -# Disabling Annotations +## Disabling Annotations If for some reason you do not wish annotations to be written, they may be disabled with `--github-annotations=false`. diff --git a/asf-site-src/source/documentation/in-progress/precommit/index.html.md b/asf-site-src/source/documentation/in-progress/precommit/index.html.md index 34d27dea0..fc98c8d58 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/index.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/index.html.md @@ -33,7 +33,7 @@ -# Purpose +## 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. @@ -41,7 +41,7 @@ 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 +## 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. @@ -49,7 +49,7 @@ All patches to the source base go through a test that does some (relatively) lig * 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 +## 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. @@ -156,7 +156,7 @@ Language Support, Licensing, and more: * [shellcheck](plugins/shellcheck) * [SpotBugs](plugins/spotbugs) -# Related Utilities +## Related Utilities `precommit` also comes with some utilities that are useful in various capacities without needing to use the full `test-patch` runtime: @@ -167,7 +167,7 @@ capacities without needing to use the full `test-patch` runtime: * [qbt](qbt) - Quality Build Tool, for branch-specific testing * [smart-apply-patch](smart-apply-patch) - CLI manipulation and query of patch files, PRs, and more -# More information +## More information * [Usage Introduction](usage-intro) * [Advanced Usage Guide](advanced) diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/ansiblelint.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/ansiblelint.html.md index dd5ea93f2..26aecd638 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/ansiblelint.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/ansiblelint.html.md @@ -21,30 +21,30 @@ ansiblelint -# Category +## Category Test -# Description +## Description When [Ansible](https://www.ansible.com/) playbooks are detected (a file matching the pattern `playbooks/*.yml` or `playbooks/*.yaml`), runs [ansiblelint](https://ansible-lint.readthedocs.io) against those files. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--ansiblelint=` | Location of `ansible-lint` executable | +| Option | Notes | +| :--------------------- | :------------------------------------ | +| `--ansiblelint=` | Location of `ansible-lint` executable | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/ant.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/ant.html.md index a3bc15b4c..3ca0a2816 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/ant.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/ant.html.md @@ -21,33 +21,33 @@ ant -# Category +## Category Build Tool -# Description +## Description Provides support for the [Apache Ant](https://ant.apache.org) build tool. -# Environment Variables +## Environment Variables -| Variable | Passed to Docker | Notes | -|:---------|:-----------------|:------| -| `ANT_ARGS` | YES | Additional arguments to `ant` | -| `ANT_HOME` | YES | Used to determine the location of the `ant` binary if it is not on the path or provided via the `--ant-cmd` flag | -| `ANT_OPTS` | YES | Additional options to the JVM that runs `ant` | +| Variable | Passed to Docker | Notes | +| :--------- | :--------------- | :--------------------------------------------------------------------------------------------------------------- | +| `ANT_ARGS` | YES | Additional arguments to `ant` | +| `ANT_HOME` | YES | Used to determine the location of the `ant` binary if it is not on the path or provided via the `--ant-cmd` flag | +| `ANT_OPTS` | YES | Additional options to the JVM that runs `ant` | -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :---------- | :------------------------------------------------ | | `--ant-cmd` | Specifically set the location of the `ant` binary | -# Docker Notes +## Docker Notes * `${HOME}/.ivy2` is mounted to `/home/${USER_NAME}/.ivy2` in the container. * `ANT_OPTS` and `ANT_ARGS` are populated into the container environment. -# Developer Notes +## Developer Notes See [build tools](../../buildtools) for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/asflicense.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/asflicense.html.md index f9bca71c0..18b2b04a7 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/asflicense.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/asflicense.html.md @@ -21,32 +21,32 @@ asflicense -# Category +## Category Test -# Description +## Description Runs the [Apache Creadur](http://creadur.apache.org) project's [Rat](http://creadur.apache.org/rat/) code to verify software licensing. Currently, `ant`, `gradle`, and `maven` have built-in support. The Apache Yetus container image also provides the jar file in /opt/apache-rat. For other build tools/scenarios, the rat jar will need to be provided. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--asflicense-rat-excludes=` | When running rat outside of a build tool, specify the location of the exclusion file | -| `--asflicense-rat-globalexcludes=` | Apply the global excludes file after Apache Rat has run (default: true) | -| `--asflicense-rat-jar=` | When running rat outside of a build tool, specify the location of the Java jar file to execute. Defaults to /opt/apache-rat/apache-rat.jar | +| Option | Notes | +| :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | +| `--asflicense-rat-excludes=` | When running rat outside of a build tool, specify the location of the exclusion file | +| `--asflicense-rat-globalexcludes=` | Apply the global excludes file after Apache Rat has run (default: true) | +| `--asflicense-rat-jar=` | When running rat outside of a build tool, specify the location of the Java jar file to execute. Defaults to /opt/apache-rat/apache-rat.jar | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/author.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/author.html.md index 5cc4a0f05..6773317cb 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/author.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/author.html.md @@ -21,26 +21,26 @@ author -# Category +## Category Test -# Description +## Description Prevent `@``author` string from appearing the source tree. Many Java-based open source projects specifically prohibit this entry. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/autoconf.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/autoconf.html.md index e847562d9..56c17a9ff 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/autoconf.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/autoconf.html.md @@ -21,28 +21,28 @@ autoconf -# Category +## Category Build Tool -# Description +## Description Provides support for the [GNU Autoconf](https://www.gnu.org/software/autoconf/) environment. It currently does not support file systems with spaces in the path. It depends upon the `make` plug-in also being available. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :----------------------------------- | :---------------------- | | `--autoconf-configure-flags=` | Set `./configure` flags | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes See [build tools](../../buildtools) for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/blanks.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/blanks.html.md index 79bc19e5c..c7883ad53 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/blanks.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/blanks.html.md @@ -21,11 +21,11 @@ blanks -# Category +## Category Test -# Description +## Description Provides a test to do two things: @@ -34,21 +34,21 @@ Provides a test to do two things: By default, blanks will automatically ignore tabs in Makefiles and Go-related files. However, if a file is provided, that file must also include the appropriate regexs for Makefiles and Go. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--blanks-eol-ignore-file=` | File containing regexs of files/dirs to ignore EOL blanks. Defaults to `.yetus/blanks-eol.txt` | -| `--blanks-tabs-ignore-file=` | File containing regexs of files/dirs to ignore tabs. Defaults to `.yetus/blanks-tabs.txt` | +| Option | Notes | +| :--------------------------------- | :--------------------------------------------------------------------------------------------- | +| `--blanks-eol-ignore-file=` | File containing regexs of files/dirs to ignore EOL blanks. Defaults to `.yetus/blanks-eol.txt` | +| `--blanks-tabs-ignore-file=` | File containing regexs of files/dirs to ignore tabs. Defaults to `.yetus/blanks-tabs.txt` | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/briefreport.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/briefreport.html.md index 253e8ff01..8016638db 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/briefreport.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/briefreport.html.md @@ -21,29 +21,29 @@ briefreport -# Category +## Category Bug System -# Description +## Description This plug-in provides a very no-nonsense, text-based report of a run. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--brief-report-file=` | Name of the output file | +| Option | Notes | +| :------------------------------ | :---------------------------------------------------------------------- | +| `--brief-report-file=` | Name of the output file | | `--brief-report-long=` | Seconds to use to determine if a test should be considered long running | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/buf.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/buf.html.md index 549287fd4..f437a30ea 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/buf.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/buf.html.md @@ -23,31 +23,31 @@ buf buflint bufcompat -# Category +## Category Test -# Description +## Description [buf](https://github.com/bufbuild/buf) is a protobuf linter (`buflint`) and backward compatibility checker (`bufcompat`), version 0.34.0 or higher. In order to use either `buflint` or `bufcompat`, `buf` must also be enabled. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--buf=` | path to `buf` executable if it is not on the path | -| `--buf-basedir=` | set the starting dir to run buf | -| `--buf-timeout=###u` | Set the buf timeout | +| Option | Notes | +| :-------------------- | :------------------------------------------------ | +| `--buf=` | path to `buf` executable if it is not on the path | +| `--buf-basedir=` | set the starting dir to run buf | +| `--buf-timeout=###u` | Set the buf timeout | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/bugzilla.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/bugzilla.html.md index 096268433..2e889d626 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/bugzilla.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/bugzilla.html.md @@ -21,30 +21,30 @@ bugzilla -# Category +## Category Bug System -# Description +## Description Ability to read patch attachments from [Bugzilla](https://www.bugzilla.org/)-based systems. NOTE: It currently lacks the ability to write a response. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :-------------------------- | :---------------------------- | | `--bugzilla-base-url=` | URL of the Bugzilla instance. | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/cc.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/cc.html.md index 5a8fb485e..322faf132 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/cc.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/cc.html.md @@ -21,26 +21,26 @@ cc -# Category +## Category Compile -# Description +## Description Gives the ability to interpret C/C++ compiler errors. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/checkmake.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/checkmake.html.md index df8b7130b..21f5bb310 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/checkmake.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/checkmake.html.md @@ -21,29 +21,29 @@ checkmake -# Category +## Category Test -# Description +## Description Runs [checkmake](https://github.com/mrtazz/checkmake) when the presence of a Makefile is found. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--checkmake=` | Location of the `checkmake` binary if it is not on the path | +| Option | Notes | +| :-------------------------- | :------------------------------------------------------------------------------- | +| `--checkmake=` | Location of the `checkmake` binary if it is not on the path | | `--checkmake-config=` | Location of `checkmake`'s configuration file, if it is not in a default location | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/checkstyle.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/checkstyle.html.md index b9070f701..d6e8bf32a 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/checkstyle.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/checkstyle.html.md @@ -21,30 +21,30 @@ checkstyle -# Category +## Category Test -# Description +## Description [checkstyle](https://checkstyle.sourceforge.net/) is a style linter for Java and many Java-adjacent languages. This plugin requires support from the [Build Tool](../../buildtools) in order to work correctly. At present, support for `ant`, `maven`, and `gradle` are built-in. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :------------------------- | :----------------------------------------------------------------------------- | | `--checkstyle-goal=` | Choose between `check` or `checkstyle` Maven goals. Defaults to `checkstyle`. | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/cmake.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/cmake.html.md index edaa1d6fc..9e3dbe21d 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/cmake.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/cmake.html.md @@ -21,37 +21,37 @@ cmake -# Category +## Category Build Tool -# Description +## Description Enables using [cmake](https://cmake.org/) as the build tool. This plug-in has a dependency on the `make` plug-in. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--cmake-build-dir=` | Relative to each module, the location of the build directory to use for storing built output | -| `--cmake-cmd=` | Location of `cmake`'s executable, if it is not on the path | -| `--cmake-root-build=` | Enable/Disable module support if multiple CMakeLists.txt's are found | +| Option | Notes | +| :-------------------------- | :------------------------------------------------------------------------------------------- | +| `--cmake-build-dir=` | Relative to each module, the location of the build directory to use for storing built output | +| `--cmake-cmd=` | Location of `cmake`'s executable, if it is not on the path | +| `--cmake-root-build=` | Enable/Disable module support if multiple CMakeLists.txt's are found | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes There are two variables that personalities should probably set that correspond to two of the options above: -| Variable | Option Equivalent | -|:---------|:------| -| CMAKE_BUILD_DIR | `--cmake-build-dir=` | +| Variable | Option Equivalent | +| :--------------- | :-------------------------- | +| CMAKE_BUILD_DIR | `--cmake-build-dir=` | | CMAKE_ROOT_BUILD | `--cmake-root-build=` | See [build tools](../../buildtools) for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/codespell.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/codespell.html.md index fba303a6d..c6e49d6c1 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/codespell.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/codespell.html.md @@ -21,11 +21,11 @@ codespell -# Category +## Category Test -# Description +## Description Runs [codespell](https://github.com/codespell-project/codespell) on the repository. @@ -33,20 +33,20 @@ Due to how `codespell` executes, `./` is prefixed onto paths at runtime. This p to be a bit more consistent with how one would run it from the command line such that `.codespellrc` is easier to manage. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :--------------------------------- | :------------------------------------------------------------------------------- | | `--codespell-exclude-lines=` | File of lines that codespell should ignore (defaults to `.codespellignorelines`) | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/compile.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/compile.html.md index 61c68e654..665ccefa6 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/compile.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/compile.html.md @@ -21,30 +21,30 @@ compile -# Category +## Category Test -# Description +## Description Enable the compile cycle and any enabled Compile-type tests of precommit. This plug-in must be turned on in order to activate any other plug-ins that are of type Compile. -# Requirements +## Requirements None -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/ctest.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/ctest.html.md index 6baf291cf..d8a28c8e1 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/ctest.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/ctest.html.md @@ -21,26 +21,26 @@ ctest -# Category +## Category Test Format -# Description +## Description Finds all `LastTestsFailed.log` files and processes them as though they were generated by [ctest](https://cmake.org/cmake/help/latest/manual/ctest.1.html). -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/detsecrets.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/detsecrets.html.md index 83249b06a..f6e83af09 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/detsecrets.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/detsecrets.html.md @@ -21,36 +21,36 @@ detsecrets -# Category +## Category Test -# Description +## Description Runs [detect-secrets](https://github.com/yelp/detect-secrets). NOTE: This test also requires a working Python 3.4+ interpreter available on the path. It will be called first as `python3` and secondarily as `python`. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--detsecrets=` | Location of the `detect-secrets` binary if it is not on the path. Default is 'detect-secrets'. | -| `--detsecrets-files=` | Regex of files to ignore. | -| `--detsecrets-hashes-to-ignore=` | Filename of a list of hashes to ignore Default is .yetus/detsecrets-ignored-hashes.txt' | -| `--detsecrets-lines=` | Regex of lines to ignore. | -| `--detsecrets-secrets=` | Regex of secrets to ignore. | +| Option | Notes | +| :------------------------------------- | :---------------------------------------------------------------------------------------------- | +| `--detsecrets=` | Location of the `detect-secrets` binary if it is not on the path. Default is 'detect-secrets'. | +| `--detsecrets-files=` | Regex of files to ignore. | +| `--detsecrets-hashes-to-ignore=` | Filename of a list of hashes to ignore Default is .yetus/detsecrets-ignored-hashes.txt' | +| `--detsecrets-lines=` | Regex of lines to ignore. | +| `--detsecrets-secrets=` | Regex of secrets to ignore. | -# Docker Notes +## Docker Notes The IBM version is based upon 0.13 and is slightly incompatible with the Yelp version. The docker container includes the Yelp version. Using the IBM version may result in some weirdness. -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/dupname.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/dupname.html.md index 059081da4..796a2b037 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/dupname.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/dupname.html.md @@ -21,11 +21,11 @@ dupname -# Category +## Category Test -# Description +## Description Checks for file system objects in the git repository that conflict due to case. For example, if the source repository contains: @@ -39,18 +39,18 @@ All three would be flagged as only one could exist on a case insensitive file sy NOTE: This test is ALWAYS enabled. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/github.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/github.html.md index 7599f8a3d..90d4ee29e 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/github.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/github.html.md @@ -21,28 +21,28 @@ github -# Category +## Category Bug System -# Description +## Description Enables support for reading and writing back to [GitHub](https://github.com/) and compatible systems such as GitHub Enterprise. See also the [Bugsystems](../../bugsystems) documentation for more information. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--github-annotations-limit=` | Max number of GitHub Checks Annotations to attempt | -| `--github-api-url=` | REST API URL (for GitHub Enterprise) | -| `--github-base-url=` | Non-REST API URL (for GitHub Enterprise) | -| `--github-repo=` | `username/repository` identifier | -| `--github-status-use-htmlreport=` | Use htmlout for Github Status 'Details' link | -| `--github-token=` | Token used to perform read and write operations | +| Option | Notes | +| :-------------------------------------- | :------------------------------------------------- | +| `--github-annotations-limit=` | Max number of GitHub Checks Annotations to attempt | +| `--github-api-url=` | REST API URL (for GitHub Enterprise) | +| `--github-base-url=` | Non-REST API URL (for GitHub Enterprise) | +| `--github-repo=` | `username/repository` identifier | +| `--github-status-use-htmlreport=` | Use htmlout for Github Status 'Details' link | +| `--github-token=` | Token used to perform read and write operations | ## HTML Details LInk @@ -51,10 +51,10 @@ a GitHub PR using the Github Multibranch Plug-in), the Details will link to the the robot's console after the run is complete. The report file must either be relative to the normal `--patch-dir` or be forcibly set using the `--html-report-url`. -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes All of the command line settings may also be set via internal environment variables. However care must be taken to not step on [robots](../../robots) that will also set some of these variables. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/gitlab.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/gitlab.html.md index 21bbab141..8c5fd67dd 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/gitlab.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/gitlab.html.md @@ -21,31 +21,31 @@ gitlab -# Category +## Category Bug System -# Description +## Description Enables support for reading and writing back to [Gitlab](https://gitlab.com/) and compatible systems such as Gitlab Enterprise. See also the [Bugsystems](../../bugsystems) documentation for more information. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :----------------------- | :---------------------------------------- | | `--gitlab-disable-write` | Turn off writing to Gitlab merge requests | -| `--gitlab-repo=` | `username/repository` identifier | -| `--gitlab-token=` |OAuth 2.0 token to use for authentication | -| `--gitlab-url=` | REST API URL (for Gitlab Enterprise) | +| `--gitlab-repo=` | `username/repository` identifier | +| `--gitlab-token=` | OAuth 2.0 token to use for authentication | +| `--gitlab-url=` | REST API URL (for Gitlab Enterprise) | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes All of the command line settings may also be set via internal environment variables. However care must be taken to not step on [robots](../../robots) that will also set some of these variables. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/golang.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/golang.html.md index 2b86fcace..493090513 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/golang.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/golang.html.md @@ -21,11 +21,11 @@ golang -# Category +## Category Test (Compile) -# Description +## Description NOTE: Go support is experimental. @@ -33,17 +33,17 @@ Provides support for [Go](https://golang.com) v1.12 and higher. This support in Amongst other missing features, it does not support using Go as a [build tool](../../buildtools) or `go test` formatted output. Additionally, if Go source is detected, `precommit` will use `git checkout` in addition to `git clean` to maintain the source tree as part of the compile cycle. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :------------------ | :--------------------------------------------------- | | `--golang-go=` | Location of the `go` binary if it is not on the path | -# Docker Notes +## Docker Notes The following standard Go compiler variables are passed onto the container environment: @@ -52,6 +52,6 @@ The following standard Go compiler variables are passed onto the container envir * GO111MODULE * GOPATH -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/golangcilint.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/golangcilint.html.md index 5037393e5..832bb68cd 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/golangcilint.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/golangcilint.html.md @@ -21,11 +21,11 @@ golangcilint -# Category +## Category Test -# Description +## Description NOTE: This plug-in only supports Go using Go modules. @@ -33,21 +33,21 @@ Provides support for [golangci-lint](https://github.com/golangci/golangci-lint). This plug-in requires the [golang](../golang) plug-in to also be enabled. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--golangcilint=` | Location of the `golangci-lint` binary if it is not on the path | -| `--golangcilint-config=` | Override the default location of the configuration file | +| Option | Notes | +| :----------------------------- | :-------------------------------------------------------------- | +| `--golangcilint=` | Location of the `golangci-lint` binary if it is not on the path | +| `--golangcilint-config=` | Override the default location of the configuration file | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/gradle.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/gradle.html.md index 9fc5567a9..7e4b4e789 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/gradle.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/gradle.html.md @@ -21,29 +21,29 @@ gradle -# Category +## Category Build Tool -# Description +## Description Provides support for the [Gradle](https://www.gradle.org/) environment. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--gradle-cmd=` | Set the location of the `gradle` command | +| Option | Notes | +| :--------------------- | :---------------------------------------- | +| `--gradle-cmd=` | Set the location of the `gradle` command | | `--gradlew-cmd=` | Set the location of the `gradlew` command | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes See [build tools](../../buildtools) for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/hadolint.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/hadolint.html.md index ce6e2b65c..a80d4e9ea 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/hadolint.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/hadolint.html.md @@ -21,28 +21,28 @@ hadolint -# Category +## Category Test -# Description +## Description Runs [hadolint](https://github.com/hadolint/hadolint) when the presence of a Dockerfile is found. * A locale with UTF-8 support is required. If the locale is not UTF-8 compliant, the locale will be forcibly set to C.UTF-8. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/htmlout.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/htmlout.html.md index ede214ce8..55abe9990 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/htmlout.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/htmlout.html.md @@ -21,30 +21,30 @@ htmlout -# Category +## Category Bug System -# Description +## Description This plug-in provides an HTML report snippet of the standard report for inclusion into a properly formatted HTML document. [Example output](htmlout-example.html) -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--html-report-file=` | Name of the output file | -| `--html-report-url=` | Override the default URL for using the HTML report | +| Option | Notes | +| :-------------------------- | :------------------------------------------------- | +| `--html-report-file=` | Name of the output file | +| `--html-report-url=` | Override the default URL for using the HTML report | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/javac.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/javac.html.md index c863510ee..3cb8e3dc7 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/javac.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/javac.html.md @@ -21,11 +21,11 @@ javac -# Category +## Category Test (Compile) -# Description +## Description Provides support for [Java](https://java.net) compilation. @@ -33,22 +33,22 @@ The location of Java must be configured either via the command line (--) or via The `JAVA_HOME`/`--java-home` JDK is considered the base JDK and will always be used last when `--multijdk` options are used. Therefore, it should **always** be the earliest version so that bytecode remains compatible between versions. -# Environment Variables +## Environment Variables `JAVA_HOME` may be used to set the location of the JDK. -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--java-home` | The base JDK to use for Java work | -| `--multijdkdirs=` | Comma delimited list of directories to treat as JDKs | +| Option | Notes | +| :--------------------------------- | :---------------------------------------------------------------------------------------------------- | +| `--java-home` | The base JDK to use for Java work | +| `--multijdkdirs=` | Comma delimited list of directories to treat as JDKs | | `--multijdktests=` | Comma delimited list of tests that support MultiJDK mode that should actually be run in MultiJDK mode | -# Docker Notes +## Docker Notes Locations should be local to the Docker container image. -# Developer Notes +## Developer Notes * Options are actually handled by `test-patch` directly due to intertwined nature of them. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/javadoc.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/javadoc.html.md index 11415ca21..1e1705605 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/javadoc.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/javadoc.html.md @@ -21,28 +21,28 @@ javadoc -# Category +## Category Test -# Description +## Description Provides support for [Javadoc](https://java.net) testing. See the [javac](javac.html) plugin for more information. -# Environment Variables +## Environment Variables See the [javac](javac.html) plugin for more information. -# Options +## Options See the [javac](javac.html) plugin for more information. -# Docker Notes +## Docker Notes See the [javac](javac.html) plugin for more information. -# Developer Notes +## Developer Notes See the [javac](javac.html) plugin for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/jira.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/jira.html.md index 9e2059ee9..a7953c08e 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/jira.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/jira.html.md @@ -21,32 +21,32 @@ jira -# Category +## Category Bug System -# Description +## Description Enables support for reading and writing back to [JIRA](https://www.atlassian.com/software/jira), both on-premise and in-cloud. See also the [Bugsystems](../../bugsystems) documentation for more information. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--jira-base-url=` | URL for the JIRA installation | -| `--jira-issue-re=` | regular expression to use when trying to find a JIRA ref in the patch name | -| `--jira-password=` | Password to use for authentication | +| Option | Notes | +| :------------------------ | :---------------------------------------------------------------------------------------------- | +| `--jira-base-url=` | URL for the JIRA installation | +| `--jira-issue-re=` | regular expression to use when trying to find a JIRA ref in the patch name | +| `--jira-password=` | Password to use for authentication | | `--jira-status-re=` | Grep regular expression representing the issue status whose patch is applicable to the codebase | -| `--jira-user=` | Username to use for authentication | +| `--jira-user=` | Username to use for authentication | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/jshint.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/jshint.html.md index a386c7b87..3f8c9c2ac 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/jshint.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/jshint.html.md @@ -21,28 +21,28 @@ jshint -# Category +## Category Test -# Description +## Description Execute [jsint](https://jshint.com/) against JavaScript code. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :------------- | :------------------ | | `--jshint-cmd` | Executable location | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/jsonlint.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/jsonlint.html.md index 78b6b883a..1982c098a 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/jsonlint.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/jsonlint.html.md @@ -21,28 +21,28 @@ jsonlint -# Category +## Category Test -# Description +## Description [jsonlint](https://github.com/zaach/jsonlint) lints JSON. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :------------------ | :--------------------------------------------------------- | | `--jsonlint=` | Location of the `jsonlint` binary if it is not on the path | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/junit-bugsystem.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/junit-bugsystem.html.md index f19d5335c..75dc47fb6 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/junit-bugsystem.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/junit-bugsystem.html.md @@ -21,11 +21,11 @@ junit -# Category +## Category Bug System -# Description +## Description The `junit` Bug System provides output of failed tests in [junit](https://svn.apache.org/repos/asf/ant/core/trunk/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java) format. @@ -33,16 +33,16 @@ NOTE: * there is no formal specification of the format so results parsing the output may be mixed. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--junit-report-style=[full\|line]` | Style of the junit report | -| `--junit-report-xml=` | Name of the output file | +| Option | Notes | | +| :--------------------------- | :---------------------- | :------------------------ | +| `--junit-report-style=[full\ | line]` | Style of the junit report | +| `--junit-report-xml=` | Name of the output file | | ## JUnit Style @@ -51,10 +51,10 @@ The JUnit report type has two formats: * `full` - summarizes per-test and provides a link to the report for that test * `line` - summarizes per-file and works better with integrated CI systems and with external readers such as Jenkins WarningNG plug-in -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/junit-testformat.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/junit-testformat.html.md index def02e465..cfb0d0753 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/junit-testformat.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/junit-testformat.html.md @@ -21,11 +21,11 @@ junit -# Category +## Category Test Format -# Description +## Description The `junit` test format attempts to process test data as documented in [junit](https://svn.apache.org/repos/asf/ant/core/trunk/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java) format. @@ -33,21 +33,21 @@ NOTE: * there is no formal specification of the format so results parsing the output may be mixed. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--junit-test-output=` | Directory to search for the test output TEST-*.xml files, relative to the module directory | -| `--junit-test-prefix=` | Prefix to trim from test names to reduce the amount of output | +| Option | Notes | +| :------------------------------------- | :----------------------------------------------------------------------------------------- | +| `--junit-test-output=` | Directory to search for the test output TEST-*.xml files, relative to the module directory | +| `--junit-test-prefix=` | Prefix to trim from test names to reduce the amount of output | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/make.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/make.html.md index 16e19ad77..0c6288648 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/make.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/make.html.md @@ -21,38 +21,38 @@ make -# Category +## Category Build Tool -# Description +## Description Enables using the various forms of make as the build tool. This includes [GNU make](https://www.gnu.org/software/make/) and [BSD make](https://www.freebsd.org/cgi/man.cgi?make(1)). Currently, this plugin makes assumptions about what are valid targets: -| Target | Function | -|:-------|:---------| -| clean | Clean the directory, keeping any configuration objects such as from `autoconf`. (See also `--make-use-git-clean`) | -| distclean | Clean the directory back to a pristine shape. (See also `--make-use-git-clean`) | -| test | Perform unit testing | +| Target | Function | +| :-------- | :----------------------------------------------------------------------------------------------------------------- | +| clean | Clean the directory, keeping any configuration objects such as from `autoconf`. (See also `--make-use-git-clean`) | +| distclean | Clean the directory back to a pristine shape. (See also `--make-use-git-clean`) | +| test | Perform unit testing | -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--make-cmd=` | Executable location | -| `--make-file=` | Filename to use instead of the default `Makefile` | -| `--make-use-git-clean` | Instead of `make clean`, use `git clean` to wipe the repository | +| Option | Notes | +| :----------------------- | :-------------------------------------------------------------- | +| `--make-cmd=` | Executable location | +| `--make-file=` | Filename to use instead of the default `Makefile` | +| `--make-use-git-clean` | Instead of `make clean`, use `git clean` to wipe the repository | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes See [build tools](../../buildtools) for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/markdownlint.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/markdownlint.html.md index 58b6f3262..462a33d80 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/markdownlint.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/markdownlint.html.md @@ -21,26 +21,26 @@ markdownlint -# Category +## Category Test -# Description +## Description Runs [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) when the presence of Markdown files are found. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/maven.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/maven.html.md index 9271830e7..7a08cb629 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/maven.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/maven.html.md @@ -21,33 +21,33 @@ maven -# Category +## Category Build Tool -# Description +## Description Enables [Apache Maven](https://maven.apache.org) as the controlling build tool. -# Environment Variables +## Environment Variables `MAVEN_HOME` may be used to find the `mvn` executable. -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--mvn-cmd=` | Executable location | -| `--mvn-custom-repos` | Use custom Apache Maven repositories (generally `$WORKSPACE/yetus-m2`) instead of the default. | -| `--mvn-custom-repos-dir=` | Override the default location that test-patch will use when `--mvn-custom-repos` is enabled | -| `--mvn-deps-order=` | Disable the plug-ins auto-dependency module ordering detection | -| `--mvn-settings=` | Configuration the location of Maven\'s settings file | +| Option | Notes | +| :----------------------------- | :--------------------------------------------------------------------------------------------- | +| `--mvn-cmd=` | Executable location | +| `--mvn-custom-repos` | Use custom Apache Maven repositories (generally `$WORKSPACE/yetus-m2`) instead of the default. | +| `--mvn-custom-repos-dir=` | Override the default location that test-patch will use when `--mvn-custom-repos` is enabled | +| `--mvn-deps-order=` | Disable the plug-ins auto-dependency module ordering detection | +| `--mvn-settings=` | Configuration the location of Maven\'s settings file | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes The `maven` plug-in adds several API calls that other plug-ins may use to configure specific Apache Maven behavior, generally around Maven cache management. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/nobuild.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/nobuild.html.md index 6a6af8441..6ebf7e3b7 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/nobuild.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/nobuild.html.md @@ -21,26 +21,26 @@ nobuild -# Category +## Category Build Tool -# Description +## Description A stub build tool that does not do anything. Use this if you would like to enable static linting without getting Yetus to work with your project's build system. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/pathlen.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/pathlen.html.md index 47a07e615..697fdfb52 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/pathlen.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/pathlen.html.md @@ -21,29 +21,29 @@ pathlen -# Category +## Category Test -# Description +## Description Verifies that file paths in the source tree are less than a certain length. This check helps to guarantee that the repository will always work on limited file systems. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :------------------------- | :--------------------------------------------------------- | | `--pathlen-size=` | Set the acceptable size limit. Defaults to 240 characters | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/perlcritic.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/perlcritic.html.md index 1ef457940..dd5e2fcbe 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/perlcritic.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/perlcritic.html.md @@ -21,30 +21,30 @@ perlcritic -# Category +## Category One or more of: Test -# Description +## Description Runs [perlcritic](http://perlcritic.com/) against Perl code. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :-------------------- | :----------------------------------------------------------- | | `--perlcritic=` | Location of the `perlcritic` binary if it is not on the path | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/pylint.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/pylint.html.md index 931c0c8af..9c99a8456 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/pylint.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/pylint.html.md @@ -21,33 +21,33 @@ pylint -# Category +## Category Test -# Description +## Description Runs [pylint](http://pylint.org/) against Python code. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--pylint=` | Location of the `pylint` binary if it is not on the path. Default is 'pylint'. | -| `--pylint-ignore-bad-option-value=` | Ignore `bad-option-value` errors. Default is 'true' | -| `--pylint-pip-cmd=` | Location of the `pip` binary for install requirements.txt files. Default is 'pip'. | -| `--pylint-rcfile=` | Location of the `.pylintrc` file to override `pylint` default. | -| `--pylint-requirements=` | Process any `requirements.txt` file. Default is 'false'. | -| `--pylint-use-user=` | Use `--user` for processing the `requirements.txt` file. Default is 'true'. | +| Option | Notes | +| :---------------------------------------- | :---------------------------------------------------------------------------------- | +| `--pylint=` | Location of the `pylint` binary if it is not on the path. Default is 'pylint'. | +| `--pylint-ignore-bad-option-value=` | Ignore `bad-option-value` errors. Default is 'true' | +| `--pylint-pip-cmd=` | Location of the `pip` binary for install requirements.txt files. Default is 'pip'. | +| `--pylint-rcfile=` | Location of the `.pylintrc` file to override `pylint` default. | +| `--pylint-requirements=` | Process any `requirements.txt` file. Default is 'false'. | +| `--pylint-use-user=` | Use `--user` for processing the `requirements.txt` file. Default is 'true'. | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/revive.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/revive.html.md index e7e6de723..4850a577a 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/revive.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/revive.html.md @@ -21,31 +21,31 @@ revive -# Category +## Category One or more of: Test -# Description +## Description [revive](https://revive.run/) is an advanced Go linter. It acts as a drop-in replacement for `golint` but with more features and allows for exceptions. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--revive=` | Location of the `revive` binary if it is not on the path | +| Option | Notes | +| :----------------------- | :---------------------------------------------------------------------------- | +| `--revive=` | Location of the `revive` binary if it is not on the path | | `--revive-config=` | Location of `revive`'s configuration file, if it is not in a default location | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/rubocop.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/rubocop.html.md index 41f0226f6..80be0593e 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/rubocop.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/rubocop.html.md @@ -21,31 +21,31 @@ rubocop -# Category +## Category One or more of: Test -# Description +## Description Runs [rubocop](https://rubocop.org/) against Ruby code. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--rubocop=` | Location of the `rubocop` binary if it is not on the path | +| Option | Notes | +| :------------------------ | :------------------------------------------------------------- | +| `--rubocop=` | Location of the `rubocop` binary if it is not on the path | | `--rubocop-config=` | Relative path to rubocop config in source tree [default: none] | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/scalac.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/scalac.html.md index da862e7fe..e848002ef 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/scalac.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/scalac.html.md @@ -21,26 +21,26 @@ scalac -# Category +## Category Test (Compile) -# Description +## Description Provides support for [Scala](https://scala-lang.org/) compilation. -# Environment Variables +## Environment Variables See the [javac](javac.html) plugin for more information. -# Options +## Options See the [javac](javac.html) plugin for more information. -# Docker Notes +## Docker Notes See the [javac](javac.html) plugin for more information. -# Developer Notes +## Developer Notes See the [javac](javac.html) plugin for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/scaladoc.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/scaladoc.html.md index feef571b3..138fea1c1 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/scaladoc.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/scaladoc.html.md @@ -21,26 +21,26 @@ scaladoc -# Category +## Category Test (Compile) -# Description +## Description Provides support for [Scaladoc](https://scala-lang.org/) documentation system. -# Environment Variables +## Environment Variables See the [javac](javac.html) plugin for more information. -# Options +## Options See the [javac](javac.html) plugin for more information. -# Docker Notes +## Docker Notes See the [javac](javac.html) plugin for more information. -# Developer Notes +## Developer Notes See the [javac](javac.html) plugin for more information. diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/shellcheck.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/shellcheck.html.md index 4dc3c1bd8..98be19a9b 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/shellcheck.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/shellcheck.html.md @@ -21,11 +21,11 @@ shellcheck -# Category +## Category Test -# Description +## Description Runs [shellcheck](https://www.shellcheck.net) when the presence of a shell script is found. @@ -33,18 +33,18 @@ Runs [shellcheck](https://www.shellcheck.net) when the presence of a shell scrip * The `-x` option is always passed to `shellcheck` if the version is greater than 0.4.1. * Versions of `shellcheck` that are earlier than 0.3.5 will generate a warning that the tool is very buggy. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/slack.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/slack.html.md index 772e7fbfb..17183ab5d 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/slack.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/slack.html.md @@ -21,28 +21,28 @@ slack -# Category +## Category Bug System -# Description +## Description Send a notice to a [Slack](https://slack.com/) channel after executing. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :-------------------------- | :--------------------------- | | `--slack-webhook-url=` | The URL of the Slack channel | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/spotbugs.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/spotbugs.html.md index 953ba0a14..af360d03e 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/spotbugs.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/spotbugs.html.md @@ -21,31 +21,31 @@ spotbugs -# Category +## Category Test -# Description +## Description Runs the Java-based [SpotBugs](https://spotbugs.github.io/) utility. -# Environment Variables +## Environment Variables -| Variable | Passed to Docker | Notes | -|:---------|:-----------------|:------| -| `SPOTBUGS_HOME` | NO | Used to determine the location of the SpotBugs installation | +| Variable | Passed to Docker | Notes | +| :-------------- | :--------------- | :---------------------------------------------------------- | +| `SPOTBUGS_HOME` | NO | Used to determine the location of the SpotBugs installation | -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--spotbugs-home==` | SpotBugs home directory. There is no default. | +| Option | Notes | +| :--------------------------- | :----------------------------------------------------------------------------------- | +| `--spotbugs-home==` | SpotBugs home directory. There is no default. | | `--spotbugs-strict-precheck` | Fail patch testing if `spotbugs` determines a failure before even applying the patch | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/tap.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/tap.html.md index 1afa55594..18e962805 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/tap.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/tap.html.md @@ -21,28 +21,28 @@ tap -# Category +## Category Test Format -# Description +## Description The `tap` test format attempts to process test data generated in the [Test Anything Protocol](https://testanything.org/) format. -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :--------------------------- | :------------------------------------------------------------------------------------ | | `--tap-log-dir==` | Directory to search for the test output *.tap files, relative to the module directory | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/template.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/template.html.md index 4da91b7a2..9fb825f03 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/template.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/template.html.md @@ -21,7 +21,7 @@ tool -# Category +## Category One or more of: @@ -31,25 +31,25 @@ Compile Test Test Format -# Description +## Description Something cool -# Environment Variables +## Environment Variables None -# Options +## Options -| Option | Notes | -|:---------|:------| -| `--checkmake=` | Location of the `checkmake` binary if it is not on the path | +| Option | Notes | +| :-------------------------- | :------------------------------------------------------------------------------- | +| `--checkmake=` | Location of the `checkmake` binary if it is not on the path | | `--checkmake-config=` | Location of `checkmake`'s configuration file, if it is not in a default location | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/unitveto.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/unitveto.html.md index 4c0fd6bff..b57ab51ee 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/unitveto.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/unitveto.html.md @@ -21,32 +21,32 @@ unitveto -# Category +## Category One or more of: Test -# Description +## Description Automatically fail a patch if matching files are touched. This test is useful for code that absolutely requires human intervention. -# Environment Variables +## Environment Variables -| Variable | Passed to Docker | Notes | -|:---------|:-----------------|:------| -| `UNITVETO_RE` | NO | Same as `--unitveto-re` | +| Variable | Passed to Docker | Notes | +| :------------ | :--------------- | :---------------------- | +| `UNITVETO_RE` | NO | Same as `--unitveto-re` | -# Options +## Options -| Option | Notes | -|:---------|:------| +| Option | Notes | +| :---------------------- | :--------------------------------------------------- | | `--unitveto-re=` | Regular expression of the files/directories to fail. | -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/xml.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/xml.html.md index aba52cbc5..3618aa3b9 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/xml.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/xml.html.md @@ -21,28 +21,28 @@ xml -# Category +## Category One or more of: Test -# Description +## Description Verify if HTML and XML files can be parsed. Requires `xmllint`. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/plugins/yamllint.html.md b/asf-site-src/source/documentation/in-progress/precommit/plugins/yamllint.html.md index 03ee64bb9..01ab7ee2e 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/plugins/yamllint.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/plugins/yamllint.html.md @@ -21,26 +21,26 @@ yamllint -# Category +## Category Test -# Description +## Description Runs [yamllint](https://github.com/adrienverge/yamllint) against `.yml` or `.yaml` file extensions. -# Environment Variables +## Environment Variables None -# Options +## Options None -# Docker Notes +## Docker Notes None -# Developer Notes +## Developer Notes None diff --git a/asf-site-src/source/documentation/in-progress/precommit/qbt.html.md b/asf-site-src/source/documentation/in-progress/precommit/qbt.html.md index 72926cc39..a9bc01c47 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/qbt.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/qbt.html.md @@ -33,7 +33,7 @@ It is meant to be a way to easily get `test-patch`'s output on your current source tree. It is suitable to be run as a regularly scheduled build as part of your overall development strategy. -# Reporting +## Reporting When using an automation tool, it may be useful to use the `--console-report-file` option to send the summary email to a @@ -73,7 +73,7 @@ If your mailing lists do not allow HTML-formatted email, then the `--brief-repor NOTE: Be aware that ASF mailing lists do not allow HTML formatted email. -# Archiving +## Archiving It may be useful to save off certain files while qbt is running for more post-processing by another utility. If the `rsync` command is available, diff --git a/asf-site-src/source/documentation/in-progress/precommit/robots/buildkite.html.md b/asf-site-src/source/documentation/in-progress/precommit/robots/buildkite.html.md index f5501ef71..2b25e8419 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/robots/buildkite.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/robots/buildkite.html.md @@ -28,7 +28,7 @@ annotation added to the build console if `buildkiteannotate` bugsystem is enable If `${ARTIFACTS_PATH}` is configured, then `--patch-dir` is set to the first listed directory path with a `/yetus` suffix. However, links to the location logs must still be configured manually. -# Buildkite Annotations +## Buildkite Annotations If precommit is running in a mode such that `buildkite-agent` isn't available (e.g., using the Apache Yetus container image) the `buildkite-annotation-recovery` tool may be used to send the annotations and artifacts to Buildkite: diff --git a/asf-site-src/source/documentation/in-progress/precommit/robots/githubactions.html.md b/asf-site-src/source/documentation/in-progress/precommit/robots/githubactions.html.md index 346f6dce0..ce2145343 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/robots/githubactions.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/robots/githubactions.html.md @@ -68,39 +68,39 @@ jobs: Currently, not all arguments and parameters that can be set on the `test-patch` command line are available to set via the workflow action. Options currently supported are: -| Option | Notes | Default | More Information | -|:-------:|:----------------------------:|:-------:|:----------------:| -| basedir | same as `--basedir` | NONE | [Usage Introduction](../../usage-intro) | -| blankseolignorefile | same as `--blanks-eol-ignore-file` | `.yetus/blanks-eol.txt` | [blanks plug-in](../../plugins/blanks) | -| blankstabsignorefile | same as `--blanks-tabs-ignore-file` | `.yetus/blanks-tabs.txt` | [blanks plug-in](../../plugins/blanks) | -| bufbasedir | same as `--buf-basedir` | `.` | [buf plug-in](../../plugins/buf) | -| buildtool | same as `--build-tool` | `nobuild` | [Build Tools](../../buildtools) | -| continuousimprovement | same as `--continuous-improvement` | false | [Robots](..) | -| excludes | same as `--excludes` | `.yetus/excludes.txt` | [Usage Introduction](../../usage-intro) | -| githubtoken | same as `--github-token` | NONE | [GitHub plug-in](../../plugins/github) | -| javahome | same as `--java-home` | `/usr/lib/jvm/java-11-openjdk-amd64` | [Java-related plug-ins](../../plugins/javac) | -| patchdir | same as `--patch-dir` | NONE |[Usage Introduction](../../usage-intro) | -| pip | same as `--pylint-pip` | pip3 | [pylint plug-in](../../plugins/pylint) | -| plugins | same as `--plugins` | all,-asflicense,-author,-findbugs,-gitlab,-jira,-shelldocs | [Usage Introduction](../../usage-intro) | -| project | same as `--project` | Auto-set based upon the repository name | [Usage Introduction](../../usage-intro) | -| pylint | same as `--pylint` | pylint3 | [pylint plug-in](../../plugins/pylint) | -| reapermode | same as `--reapermode` | kill | [Advanced Usage](../../advanced) | -| reviveconfig | same as `--revive-config` | `.revive.toml` | [revive plug-in](../../plugins/revive) | -| testsfilter | same as `--tests-filter` | '' | [Usage Introduction](../../usage-intro) | +| Option | Notes | Default | More Information | +| :-------------------- | :---------------------------------- | :--------------------------------------------------------- | :------------------------------------------- | +| basedir | same as `--basedir` | NONE | [Usage Introduction](../../usage-intro) | +| blankseolignorefile | same as `--blanks-eol-ignore-file` | `.yetus/blanks-eol.txt` | [blanks plug-in](../../plugins/blanks) | +| blankstabsignorefile | same as `--blanks-tabs-ignore-file` | `.yetus/blanks-tabs.txt` | [blanks plug-in](../../plugins/blanks) | +| bufbasedir | same as `--buf-basedir` | `.` | [buf plug-in](../../plugins/buf) | +| buildtool | same as `--build-tool` | `nobuild` | [Build Tools](../../buildtools) | +| continuousimprovement | same as `--continuous-improvement` | false | [Robots](..) | +| excludes | same as `--excludes` | `.yetus/excludes.txt` | [Usage Introduction](../../usage-intro) | +| githubtoken | same as `--github-token` | NONE | [GitHub plug-in](../../plugins/github) | +| javahome | same as `--java-home` | `/usr/lib/jvm/java-21-openjdk-amd64` | [Java-related plug-ins](../../plugins/javac) | +| patchdir | same as `--patch-dir` | NONE | [Usage Introduction](../../usage-intro) | +| pip | same as `--pylint-pip` | pip3 | [pylint plug-in](../../plugins/pylint) | +| plugins | same as `--plugins` | all,-asflicense,-author,-findbugs,-gitlab,-jira,-shelldocs | [Usage Introduction](../../usage-intro) | +| project | same as `--project` | Auto-set based upon the repository name | [Usage Introduction](../../usage-intro) | +| pylint | same as `--pylint` | pylint3 | [pylint plug-in](../../plugins/pylint) | +| reapermode | same as `--reapermode` | kill | [Advanced Usage](../../advanced) | +| reviveconfig | same as `--revive-config` | `.revive.toml` | [revive plug-in](../../plugins/revive) | +| testsfilter | same as `--tests-filter` | '' | [Usage Introduction](../../usage-intro) | Items marked NONE *MUST* be provided in the workflow yaml file. Some options are hard-coded to make `test-patch` easier to use: -| Argument | Value | More Information | -|:--------:|:------:|:----------------:| -| `--brief-report-file` | patchdir/brief.txt | [briefreport plug-in](../../plugins/briefreport) | -| `--console-report-file` | patchdir/console.txt | [QBT](../../qbt) | -| `--html-report-file` | patchdir/report.html | [htmlout plug-in](../../plugins/htmlout) | -| `--ignore-unknown-options` | true | [Usage Introduction](../../usage-intro) | -| `--junit-report-xml` | patchdir/junit-report.xml | [junit plug-in](../../plugins/junit-bugsystem) | -| `--pylint-requirements` | true | [pylint plug-in](../../plugins/pylint) | -| `--report-unknown-options` | false | [Usage Introduction](../../usage-intro) | +| Argument | Value | More Information | +| :------------------------- | :------------------------ | :----------------------------------------------- | +| `--brief-report-file` | patchdir/brief.txt | [briefreport plug-in](../../plugins/briefreport) | +| `--console-report-file` | patchdir/console.txt | [QBT](../../qbt) | +| `--html-report-file` | patchdir/report.html | [htmlout plug-in](../../plugins/htmlout) | +| `--ignore-unknown-options` | true | [Usage Introduction](../../usage-intro) | +| `--junit-report-xml` | patchdir/junit-report.xml | [junit plug-in](../../plugins/junit-bugsystem) | +| `--pylint-requirements` | true | [pylint plug-in](../../plugins/pylint) | +| `--report-unknown-options` | false | [Usage Introduction](../../usage-intro) | ## Manual Configuration diff --git a/asf-site-src/source/documentation/in-progress/precommit/robots/index.html.md b/asf-site-src/source/documentation/in-progress/precommit/robots/index.html.md index 16d79b93f..7cf5f3a7b 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/robots/index.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/robots/index.html.md @@ -29,7 +29,7 @@ -# Intro +## Intro `test-patch` works hand-in-hand with various CI and other automated build systems. `test-patch` will attempt to auto-determine if it is running under such a system and change its defaults to match known configuration parameters automatically. When robots are activated, there is generally some additional/changed behavior: @@ -42,7 +42,7 @@ * activate Docker maintenance when `--docker` is passed * attempt to determine whether this is a full build (`qbt`) or testing a patch/merge request/pull request. -# Automated Robot Detection +## Automated Robot Detection The following systems are detected automatically when run in one of these environments: @@ -56,7 +56,7 @@ The following systems are detected automatically when run in one of these enviro * [Semaphore CI](semaphoreci) * [Travis CI](travisci) -# Manual Configuration +## Manual Configuration For automated systems that are not directly supported, `--robot` tells `test-patch` that this is an automated system. This will trigger many of the above settings. @@ -75,13 +75,13 @@ $ test-patch --robot --instance=1 If `--robot` is specified without an instance, a random number is generated and used. -# Sentinel Mode +## Sentinel Mode If stuck Docker containers are a problem, a more aggressive robot may be enabled with the `--sentinel` option. This option enables killing containers that have been running for over 24 hours as well. See the documentation on [docker](../docker) for more information. -# Continuous Improvement +## Continuous Improvement It isn't unusual when adding a new linter to an existing source repository to be overwhelmed with new errors. Most projects want to start out where all new patches cannot add new errors, but the existing ones are diff --git a/asf-site-src/source/documentation/in-progress/precommit/smart-apply-patch.html.md b/asf-site-src/source/documentation/in-progress/precommit/smart-apply-patch.html.md index a451928a1..2e700026b 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/smart-apply-patch.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/smart-apply-patch.html.md @@ -31,7 +31,7 @@ `smart-apply-patch` is a command to help apply patches easily. It uses the same plug-ins and many of the same options as test-patch. This means that it can, for example, fetch patches from JIRA and apply them to a local source tree. -# Local File +## Local File Its simplest form is used when a patch is stored in a local file: @@ -41,7 +41,7 @@ $ smart-apply-patch patch This will cause the command to run through various ways to verify and then apply the patch to the current repo, including deducing a patch level. -# Remote Files and Bug Systems +## Remote Files and Bug Systems `smart-apply-patch` supports many of the same switches and configurations that `test-patch` does. Using those switches means that, for example, it is possible to pull and apply a GitHub PR very easily: @@ -52,7 +52,7 @@ $ smart-apply-patch --plugins=github --github-repo apache/yetus GH:3000 `smart-apply-patch` will do all the work of downloading, verifying, and applying just as `test-patch` would. -# Dry-run +## Dry-run Perhaps you just want to see if the patch even applies without changing your local repo. The `--dry-run` option will just test for applicability: @@ -60,7 +60,7 @@ Perhaps you just want to see if the patch even applies without changing your loc $ smart-apply-patch --dry-run patch ``` -# Committer Mode +## Committer Mode For committers of projects, there is a special mode: @@ -74,7 +74,7 @@ that in addition to applying the patch will also attempt to: * add all newly created files in the repo * use `--signoff` and commit the change via git-am -# Patch Reporting +## Patch Reporting For speciality CI needs, it may be useful to just have access to Apache Yetus' ability to interpret changes and then do your own actions based upon that diff --git a/asf-site-src/source/documentation/in-progress/precommit/testformats.html.md b/asf-site-src/source/documentation/in-progress/precommit/testformats.html.md index 0fe311372..45d1a8aef 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/testformats.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/testformats.html.md @@ -44,6 +44,6 @@ Given a path to the log file and tested module name, parse that file and store t Using the results stored by pluginname\_process\_tests, write them to the test result table and/or the footer table for reporting. -# Example +## Example For an example of how to write a test-format plugin, you can look at [junit plugin](https://github.com/apache/yetus/blob/main/precommit/plugins.d/junit.sh) bundled in Apache Yetus. diff --git a/asf-site-src/source/documentation/in-progress/precommit/usage-intro.html.md b/asf-site-src/source/documentation/in-progress/precommit/usage-intro.html.md index 1044bf372..891dbfa94 100644 --- a/asf-site-src/source/documentation/in-progress/precommit/usage-intro.html.md +++ b/asf-site-src/source/documentation/in-progress/precommit/usage-intro.html.md @@ -48,7 +48,7 @@ -# First Steps +## First Steps A typical local configuration is to have two repositories. One with the code you are working on and another, clean repository. The workflow looks similar to the following: @@ -165,7 +165,7 @@ Total Elapsed time: 0m 01s `test-patch` gives extensive information about what it is doing at run time and then provides a report at the end to give a summary about what happened. In this particular case, this output just shows that the patch was applied and that no tests were actually run. -# Resetting the Repository +## Resetting the Repository After running that command, the test repository will contain the remnants of the build for later debugging. It is inconvenient to instead use: @@ -187,11 +187,11 @@ Modes: ResetRepo Some features are mostly invisible or auto-detected during runtime. The `Modes` line provides hints about those features. -# Dirty Workspaces +## Dirty Workspaces An alternative to `--resetrepo` is the `--dirty-workspace` flag. It tells test-patch that the repository is not clean and it is ok to continue. This is especially useful on a repository that is in some way 'live,' such as a repository that is actively being used for development. -# Enabling Features +## Enabling Features In general, almost all features are enabled via the plug-in framework. To see what has been enabled, use the `--list-plugins` option: @@ -248,7 +248,7 @@ $ cd $ test-patch --plugins=all ``` -# Unit Tests +## Unit Tests By default, unit tests are not run since they may take a significant amount of time. @@ -261,7 +261,7 @@ $ test-patch --plugins=all --dirty-workspace --run-tests This is the same command, but now runs the unit tests. -# Output Directory +## Output Directory After the tests have run, there is a directory that contains all of the `test-patch` related artifacts. This is generally referred to as the patch directory. By default, `test-patch` tries to make something off of `/tmp` to contain this content. Using the `--patch-dir` option, one can specify exactly which directory to use. This is helpful for automated precommit testing so that [continuous integration systems](../robots) knows where to look to gather up the output. @@ -275,7 +275,7 @@ $ test-patch --plugins=all --patch-dir=${WORKSPACE}/patchdir --basedir=${WORKSPA **NOTE: Make sure to add the patch directory to `.gitignore` if the directory is inside the source tree to avoid deleting it, as `test-patch` does a `git clean` to remove untracked files from previous runs.** -# Build Tool +## Build Tool Out of the box, `test-patch` will try to figure out which build tool the project uses. But what if you want to override it? The `--build-tool` option allows a manual setting: @@ -291,7 +291,7 @@ To disable the build tool entirely, use the `nobuild` setting: $ test-patch --plugins=all --build-tool=nobuild (other options) ``` -# Providing Patch Files +## Providing Patch Files NOTE: More in-depth information may be found in the [bugsystems](../bugsystems/) section. @@ -374,7 +374,7 @@ $ test-patch --plugins=all https://example.com/webserver/file.patch process the file.patch from the example.com webserver. -# Excluding Files +## Excluding Files Some repositories have content that is either imported from other sources (aka "vendored") or in some other way have files that are known to break tests. By default, `.yetus/excludes.txt` will be read for any @@ -388,7 +388,7 @@ $ test-patch --plugins=all --excludes=(filename) (other options) NOTE: Do not confuse file globs for regular expressions. With regular expressions, `a*` will match `aaaaaaaa` but not `ab`. To match all characters any number of times, you need `.*` as your wildcard expression. -# "Warn-only" Test Results +## "Warn-only" Test Results In some cases, test plug-ins may always generate fail results in ways that cannot be avoided or are so monumental to fix that you just want to keep track of the results without ever failing the run. `test-patch` @@ -400,7 +400,7 @@ $ test-patch --plugins=all --tests-filter=checkstyle,javadoc (other options) ... will always force the `checkstyle` and `javadoc` tests to never vote -1. -# Project-specific Capabilities +## Project-specific Capabilities Due to the extensible nature of the system, `test-patch` allows for projects to define project-specific rules which we call personalities. (How to build those rules is covered elsewhere.) There are two ways to specify which personality to use: @@ -420,7 +420,7 @@ However, `test-patch` can detect if it is a personality that is in its "personal $ test-patch --plugins=all --project=(project) ``` -# Fork Bomb Protection +## Fork Bomb Protection By default, `test-patch` will set the user soft limit (`ulimit -Su`) to a relatively low 1,000 processes (and, on some operating systems with some languages such as Java, threads!). This is to prevent errant processes from eating up all system resources. If this limit is too low, it may be necessary to use the `--proclimit` option. For example: @@ -432,7 +432,7 @@ $ test-patch --plugins=all --proclimit=10000 NOTE: The actual implementation of this feature is dependent upon the version of Bash. For bash v4 and higher (most operating systems), the fork bomb protection is generally only used for the build and QA tools. This means Apache Yetus should continue to function. For earlier versions of bash (e.g., OS X), the limit is applied to all of test-patch. If the limit is hit, Apache Yetus will itself likely crash. -# MultiJDK +## MultiJDK For many projects, it is useful to test Java code against multiple versions of JDKs at the same time. In combination with the `java` plug-in, `test-patch` can do this with the `--multijdkdirs` option: @@ -444,7 +444,7 @@ Not all Java tests support this mode, but those that do will now run their tests NOTE: JAVA\_HOME is always appended to the list of JDKs in MultiJDK mode. If JAVA\_HOME is in the list, it will be moved to the end. -# Docker +## Docker `test-patch` also has a built-in mode (i.e., no plug-in required) to utilize Docker: @@ -454,7 +454,7 @@ $ test-patch --docker This command will do some preliminary setup and then re-execute itself inside a Docker container. For more information on how to provide a custom Dockerfile and other Docker-specific features, see the specific [precommit Docker support](../docker) page and the [Apache Yetus Docker Hub Images](../../../../yetus-docker-image) page for more information on the convenience Docker images. -# Upgrading +## Upgrading Currently, Apache Yetus is still undergoing incompatible changes from time to time. Despite that, in many cases the upgrade process for `test-patch` and friends is usually just verifying what flags are being passed. To help out, @@ -462,6 +462,6 @@ there is an option to `--ignore-unknown-options` so that `test-patch` does not e longer understands. It will print a list of those unknown options in the end report. In situations where that is also undesirable, the `--report-unknown-options` may also be set simultaneously to remove the list from the report. -# In Closing +## In Closing `test-patch` has many other features and command line options for the basic user. Many of these are self-explanatory. To see the list of options, run `test-patch` without any options or with `--help`. diff --git a/asf-site-src/source/documentation/in-progress/releasedocmaker.html.md b/asf-site-src/source/documentation/in-progress/releasedocmaker.html.md index f399e868b..31926a33a 100644 --- a/asf-site-src/source/documentation/in-progress/releasedocmaker.html.md +++ b/asf-site-src/source/documentation/in-progress/releasedocmaker.html.md @@ -39,7 +39,7 @@ -# Purpose +## Purpose Building changelog information in a form that is human digestible but still containing as much useful information is difficult. Many attempts over the years have resulted in a variety of methods that projects use to solve this problem: @@ -51,13 +51,13 @@ All of these methods have their pros and cons. Some have issues with accuracy. In order to solve these problems, `releasedocmaker` was written to automatically generate a changelog and release notes by querying Apache's JIRA instance. -# Requirements +## Requirements * Python 3.8 with dateutil extension dateutil may be installed via pip: `pip3 install python-dateutil` -# Basic Usage +## Basic Usage Minimally, the name of the JIRA project and a version registered in JIRA must be provided: @@ -88,7 +88,7 @@ By default, release notes are expected to be in plain text. However, you can wr remaining text ``` -# Authentication +## Authentication `releasedocmaker` supports very simple Basic authentication. This is accomplished by adding two environment variables to your shell environment: @@ -99,7 +99,7 @@ RDM_JIRA_PASSWORD='jirapassword' These values will be added to all requests destined for the JIRA server. -# Changing the Header +## Changing the Header By default, it will use a header that matches the project name. But that is kind of ugly and the case may be wrong. Luckily, the title can be changed: @@ -109,7 +109,7 @@ $ releasedocmaker --project HBASE --version 1.2.0 --projecttitle "Apache HBase" Now instead of "HBASE", it will use "Apache HBase" for some titles and headers. -# Versioned Files and Directories +## Versioned Files and Directories It is sometimes useful to create the `CHANGELOG` and `RELEASENOTES` with versions attached. `releasedocmaker` supports both independently. @@ -133,7 +133,7 @@ $ releasedocmaker --project HBASE --version 1.2.0 --fileversions --dirversions ... results in `1.2.0/CHANGELOG.1.2.0.md` and `1.2.0/RELEASENOTES.1.2.0.md` files. -# Multiple Versions +## Multiple Versions Using either `--dirversions` or `--fileversions` or both simultaneously, `releasedocmaker` can also generate multiple versions at once @@ -151,7 +151,7 @@ $ releasedocmaker --project HBASE --version 1.0.0 --version 1.2.0 --range --file In this form, `releasedocmaker` will query JIRA, discover all versions that alphabetically appear to be between 1.0.0 and 1.2.0, inclusive, and generate all of the relative release documents. This is especially useful when bootstrapping an existing project. -# Unreleased Dates +## Unreleased Dates For released versions, releasedocmaker will pull the date of the release from JIRA. However, for unreleased versions it marks the release as "Unreleased". This can be inconvenient when actually building a release and wanting to include it inside the source package. @@ -163,7 +163,7 @@ $ releasedocmaker --project HBASE --version 1.0.0 --usetoday After using this option and release, don't forget to change JIRA's release date to match! -# Sorted Output +## Sorted Output Different projects may find one type of sort better than another, depending upon their needs. `releasedocmaker` supports two types of sorts and each provides two different options in the direction for that sort. @@ -201,7 +201,7 @@ $ releasedocmaker --project falcon --version 0.6 --sorttype issueid --sortorder In the case of multiple projects given on the command line, the projects will be grouped and then sorted by issue id. -# Backward Incompatible Changes +## Backward Incompatible Changes To check if an issue is backward-incompatible the `releasedocmaker` script first checks the "Hadoop Flags" field in the issue. If this field is found to be blank then it searches for the 'backward-incompatible' label. You can override the @@ -217,7 +217,7 @@ or equivalently using the shorter `-X` option $ releasedocmaker --project falcon --version 0.6 -X not-compatible ``` -# Lint Mode +## Lint Mode In order to ensure proper formatting while using mvn site, `releasedocmaker` puts in periods (.) for fields that are empty or unassigned. This can be unsightly and not proper for any given project. There are also other things, such as missing release notes for incompatible changes, that are less than desirable. @@ -229,7 +229,7 @@ $ releasedocmaker --project HBASE --version 1.0.0 --lint This will do the normal JIRA querying, looking for items it considers problematic. It will print the information to the screen and then exit with either success or failure, depending upon if any issues were discovered. -# Index Mode +## Index Mode There is basic support for an autoindexer. It will create two files that contain links to all directories that have a major.minor\*-style version numbering system. @@ -238,7 +238,7 @@ For example directories with names like 0.6, 1.2.2, 1.2alpha etc. will all be li * `index.md`: a file suitable for conversion to HTML via mvn site * `README.md`: a file suitable for display on Github and other Markdown rendering websites -# Release Version +## Release Version You can find the version of the `releasedocmaker` that you are using by giving the `-V` option. This may be helpful in finding documentation for the version you are using. diff --git a/asf-site-src/source/documentation/in-progress/shelldocs.html.md b/asf-site-src/source/documentation/in-progress/shelldocs.html.md index 4cd0e6ae0..a06dae455 100644 --- a/asf-site-src/source/documentation/in-progress/shelldocs.html.md +++ b/asf-site-src/source/documentation/in-progress/shelldocs.html.md @@ -35,15 +35,15 @@ -# Purpose +## Purpose Some projects have complex shell functions that act as APIs. `shelldocs` provides an annotation system similar to JavaDoc. It allows a developer to auto-generate MultiMarkdown documentation files as input to other processing systems. -# Requirements +## Requirements * Python 3.8 -# Function Annotations +## Function Annotations `shelldocs` works by doing simple parsing of shell scripts. As such, it looks for code that matches these patterns: @@ -92,14 +92,14 @@ functioname () { Note that the comment has two hash ('#') marks. The content of the comment is key. This is what `shelldocs` will turn into documentation. The following annotations are supported: -| Annotation | Required | Description | Acceptable Values | Default | -|:---- |:---- |:--- |:--- |:-- | -| @description | No | What this function does, intended purpose, etc. | text | None | -| @audience | Yes | Who should use this function? | public, private,| None | -| @stability | Yes | Is this function going to change? | stable, evolving | None | -| @replaceable | No | Is this function safely 'monkeypatched'? | yes or no | No | -| @param | No | A single parameter| A single keyword. e.g., 'seconds' to specify that this function requires a time in seconds | None | -| @return | No | What does this function return? | text | Nothing | +| Annotation | Required | Description | Acceptable Values | Default | +| :----------- | :------- | :---------------------------------------------- | :----------------------------------------------------------------------------------------- | :------ | +| @description | No | What this function does, intended purpose, etc. | text | None | +| @audience | Yes | Who should use this function? | public, private, | None | +| @stability | Yes | Is this function going to change? | stable, evolving | None | +| @replaceable | No | Is this function safely 'monkeypatched'? | yes or no | No | +| @param | No | A single parameter | A single keyword. e.g., 'seconds' to specify that this function requires a time in seconds | None | +| @return | No | What does this function return? | text | Nothing | ## Audience / Stability @@ -133,7 +133,7 @@ function add_two_numbers() { } ``` -# Basic Usage +## Basic Usage The `shelldocs` executable requires at least one input file and either an output file or to run in lint mode. Lint mode is covered below. @@ -143,7 +143,7 @@ $ shelldocs --output functions.md --input myshelldirectory This will process all of the files in `myshelldirectory` that end in `sh` and generate an output file called `functions.md`. This file will contain a table of contents of all of the functions arranged by audience, stability, and replace-ability. -# Skipping Files +## Skipping Files When processing directories, it may be desirable to avoid certain files. This may be done by including a comment in the file: @@ -153,7 +153,7 @@ When processing directories, it may be desirable to avoid certain files. This ma This comment tells `shelldocs` that this file should not be processed. -# Avoiding Private or Non-Replaceable Functions +## Avoiding Private or Non-Replaceable Functions Some functions are not meant to be used by 3rd parties or cannot be easily replaced. These functions may be omitted from the documentation by using the `--skipprnorep` flag: @@ -161,7 +161,7 @@ Some functions are not meant to be used by 3rd parties or cannot be easily repla $ shelldocs --skipprnorep --input directory --output file.md ``` -# Lint Mode +## Lint Mode In order to ensure minimal documentation, `shelldocs` has a `--lint` mode that will point out functions that are missing required annotations: diff --git a/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.html.md b/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.html.md index 8928c2eb0..59a9e684e 100644 --- a/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.html.md +++ b/asf-site-src/source/documentation/in-progress/yetus-maven-plugin.html.md @@ -29,13 +29,13 @@ -# Introduction +## Introduction Apache Yetus a plug-in built for Apache Maven and compatible build tools. This plug-in offers an easy way to integrate some of Apache Yetus' functionality in addition to offering a way to get some additional functionality that is missing from the base Maven environment. NOTE: This functionality should be considered experimental. Defaults, in particular, are likely to change in future revisions. -# File Utility Goals +## File Utility Goals As part of building Apache Yetus, we needed some portable functionality that we couldn't find elsewhere. Just so others don't have to re-invent the wheel, we offer these goals as part of the plug-in: @@ -73,15 +73,15 @@ exec "$(dirname -- "${BASH_SOURCE-0}")/../lib/shelldocs/shelldocs.py" "$@" The wrapper as written above makes sure that nearly all forms of referencing (relative, absolute, bash -x, etc.) locates the real executable, passing along any options. -| Option | Description | Default | -|--------|-------------|---------| -| `basedir` | parent dir of `bindir` and `lib` to create relative paths | `${project.build.directory}/${project.artifactId}-${project.version}` | -| `bindir` | where to create wrapper | `bin` | -| `encoding` | encoding to use when reading license files | `${project.build.sourceEncoding}` | -| `goal` | the goal to use when creating the wrappers | `package` | -| `lib` | where the actual executable is located | `lib` | -| `license` | the license to put into the wrapper. See below. | `ASL20` | -| `wrapper` | the bash wrapper to actually use | `exec "$(dirname -- "${BASH_SOURCE-0}")/../"` | +| Option | Description | Default | +| :--------- | :-------------------------------------------------------- | :-------------------------------------------------------------------- | +| `basedir` | parent dir of `bindir` and `lib` to create relative paths | `${project.build.directory}/${project.artifactId}-${project.version}` | +| `bindir` | where to create wrapper | `bin` | +| `encoding` | encoding to use when reading license files | `${project.build.sourceEncoding}` | +| `goal` | the goal to use when creating the wrappers | `package` | +| `lib` | where the actual executable is located | `lib` | +| `license` | the license to put into the wrapper. See below. | `ASL20` | +| `wrapper` | the bash wrapper to actually use | `exec "$(dirname -- "${BASH_SOURCE-0}")/../"` | ### Licenses @@ -117,13 +117,13 @@ Since Java 7, there has been a portable way to build symlinks. Unfortunately, s Available configuration options: -| Option | Description | Default | -|--------|-------------|---------| -| `basedir` | where to create the symlink, if `newLink` is not absolute | `${project.build.directory}` | -| `goal` | the goal to use when to create the symlink | `package` | -| `ignoreExist` | a boolean that determines whether the goal should fail if the `newLink` already exists. | `true`. | -| `target` | the file or directory to link to | none | -| `newLink` | the symlink to create | none | +| Option | Description | Default | +| :------------ | :-------------------------------------------------------------------------------------- | :--------------------------- | +| `basedir` | where to create the symlink, if `newLink` is not absolute | `${project.build.directory}` | +| `goal` | the goal to use when to create the symlink | `package` | +| `ignoreExist` | a boolean that determines whether the goal should fail if the `newLink` already exists. | `true`. | +| `target` | the file or directory to link to | none | +| `newLink` | the symlink to create | none | ## parallel-mkdirs @@ -149,10 +149,10 @@ Maven surefire (as of at least 2.x and earlier versions) has calculations to det Available configuration options: -| Option | Description | Default | -|--------|-------------|---------| -| `buildDir` | where to create the directories | `${project.build.directory}/test-dir` | -| `forkCount` | the number of directories to create| see blow | -| `goal` | the goal to use to create the directories | `generate-test-resources` | +| Option | Description | Default | +| :---------- | :---------------------------------------- | :------------------------------------ | +| `buildDir` | where to create the directories | `${project.build.directory}/test-dir` | +| `forkCount` | the number of directories to create | see blow | +| `goal` | the goal to use to create the directories | `generate-test-resources` | By default, `forkCount` is inherited from surefire and therefore follows the same rules as described in its [documentation](https://maven.apache.org/surefire/maven-surefire-plugin/examples/fork-options-and-parallel-execution.html). Of special note is that 'C' (aka core) values are honored. diff --git a/asf-site-src/source/yetus-docker-image.html.md b/asf-site-src/source/yetus-docker-image.html.md index d3638546e..747b33e20 100644 --- a/asf-site-src/source/yetus-docker-image.html.md +++ b/asf-site-src/source/yetus-docker-image.html.md @@ -41,7 +41,7 @@ Both images should be suitable to be used as a building block or even directly i Images are tagged such that 'main' represents the last successful Docker image build of the main branch. Images based off of the official source releases are tagged with a matching version number (e.g., 0.9.0). There is no 'latest' tagged image. It is recommended that users choose a stable tag so as not to be surprised by incompatible changes. -# File Access +## File Access All of the executables that Apache Yetus provides requires access to one or more directories. These directories should be provided on the command line via the volume flags to docker run. For example, to run shelldocs against test-patch.sh: @@ -88,6 +88,6 @@ docker build -t project/build:0.9.0 -f . This example builds a docker image based off of Apache Yetus 0.9.0 but with the additions of clang, some development libraries, and valgrind. Now project/build:0.9.0 can be used instead of ghcr.io/apache/yetus:0.14.0 since it has all of Apache Yetus and the additions needed by our project. -# A Note About Precommit +## A Note About Precommit test-patch and friends have direct support for Docker outside of the convenience images. That information is covered in-depth in the[precommit-docker](/documentation/in-progress/precommit/docker/) section. diff --git a/audience-annotations-component/pom.xml b/audience-annotations-component/pom.xml index 696873eb5..793bf458b 100644 --- a/audience-annotations-component/pom.xml +++ b/audience-annotations-component/pom.xml @@ -42,6 +42,7 @@ maven-javadoc-plugin + org.apache.yetus.audience.* diff --git a/pom.xml b/pom.xml index c8944870c..4da84c6ad 100644 --- a/pom.xml +++ b/pom.xml @@ -25,7 +25,7 @@ org.apache apache - 24 + 37 @@ -57,13 +57,14 @@ + 21 VERBOSE 3.8.1 3.8.2 3.8.2 - 11 - 11 - 11 + 21 + 21 + 21 10.18.1 2.17.0 @@ -71,11 +72,11 @@ 1.6.0 5.11.1 3.5.0 - 3.7.0 + 3.10.0 3.9.0 - 0.16.1 + 0.18 5.14.0 - 4.8.6.0 + 4.9.3.0 source-release-tar n @@ -156,21 +157,27 @@ - - org.apache.maven.plugins - maven-compiler-plugin - 3.10.1 - - - ${jigsaw.avoidance} - - - + + org.apache.maven.plugins + maven-compiler-plugin + 3.10.1 + + 21 + 21 + + + + --add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED + --add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED + ${jigsaw.avoidance} + + + org.apache.maven.plugins maven-surefire-plugin - 2.22.2 + 3.5.2 ${jigsaw.avoidance} @@ -283,19 +290,10 @@ - - maven-project-info-reports-plugin - - - - true - - - - org.apache.maven.plugins maven-javadoc-plugin + ${maven-javadoc-plugin.version} false @@ -303,12 +301,16 @@ 1024m true - false true - ${maven.compile.source} - ${maven.compile.encoding} - ${project.build.directory}/site - documentation/in-progress/javadocs + ${maven.compiler.source} + + + + ${jigsaw.avoidance} + + + -J${jigsaw.avoidance} + org.apache.yetus.audience.tools.ExcludePrivateAnnotationsStandardDoclet @@ -318,11 +320,6 @@ true - false - - org.apache.yetus:audience-annotations - - aggregate @@ -330,7 +327,6 @@ -