Skip to content

Latest commit

 

History

History
122 lines (96 loc) · 6.64 KB

CONTRIBUTING.md

File metadata and controls

122 lines (96 loc) · 6.64 KB
Raw

Contributing to exhort-java-api
java-version

Development

Common Build Goals

  • mvn test compile and run unit tests
  • mvn verify verify the project, i.e. enforce project rules, verify existing license headers, and verify code coverage threshold
  • mvn verify -Pcov create coverage reports in target/site/jacoco
  • mvn verify -Pits run integration tests
  • mvn verify -Pmut run mutation tests, will fail the build if success threshold failed to meet requirements
  • mvn verify -Pmut,dev run mutation testing, will not fail the build
  • mvn verify -Pcov,its,mut run the entire project, including coverage reports, unit, integration, and mutation tests
  • mvn install install the module locally to make at accessible to other modules running locally

Profiles Info

  • dev - use this profile for development stage, it will skip various enforcement and verification executed by the verify goal
  • cov - use this profile to create jacoco execution reports, it will create html, xml, and csv reports in target/site/jacoco
  • its - use this profile to execute integration testing, test specifications are in src/it
  • mut - use this profile to execute mutation testing, executed with pitest

The following are used strictly by CI workflows. Use mvn install to install the module locally.

  • prepare-deployment - use this profile for packaging of jars to deploy to artifact repository, it will create a flatten pom and a sources, and javadoc jars
  • deploy-github - use this profile to include github registry distribution definition, used for deploying and releasing

Good to know

  • You can override the default backend url by setting the EXHORT_DEV_MODE environment variable/system property to true:
    • In case environment variable/System Property EXHORT_DEV_MODE=true - You can Override the default exhort backend by setting
      DEV_EXHORT_BACKEND_URL env variable/system property to the desired exhort backend instance address ( useful for tests).
    • In case DEV_EXHORT_BACKEND_URL is not set via environment variable/system property, then the default DEV exhort backend is picked.
    • In case EXHORT_DEV_MODE=false or not set at all levels, then default backend url ( exhort prod) is picked, regardless of the value of DEV_EXHORT_BACKEND_URL.
    • Environment variables takes precedence over System properties - for example, if System property EXHORT_DEV_MODE=true but environment variable EXHORT_DEV_MODE=false , then default exhort prod will be used anyway.

OpenAPI Specifications

We use our Backend's OpenAPI spec file for generating types used for deserialization of the Backend's API responses.
The generated classes target package is the com.redhat.exhort.api. It is skipped when calculating coverage thresholds. Avoid writing code in this package.
When the Backend's spec file is modified, we need to manually copy it here in src/main/resources/exhort, for the openapi-generator-maven-plugin to pick it up at build time.

Modular (JPMS)

This is a modular module. If you write new packages or require new dependencies. Update the module-info.java spec accordingly. Please make an effort to avoid the use of unnamed modules.
This module is also being tested in a modular environment. Use module-info.test for configuring the environment.

Code Walkthrough

  • The ExhortApi is the Exhort Service. It implements the Api interface and provide various methods for requesting analysis reports.
  • The providers are concrete implementations of the Provider interface. And are in charge of providing content and a content type to be encapsulated in the request to the Backend. At the time of writing this, we only have one implementation, the JavaMavenProvider implementation.
  • The tools package hosts various utility tools and functions used throughout the project. Tools such as the Ecosystem for instantiating providers per manifest. And the Operations for executing process on the operating system.

Adding a Provider

  • Create a concrete implementation of the Provider abstraction and place it in the providers package.
  • In the Ecosystem class look for the getProvider function and add a switch case instantiating the new provider per file type.

Integration Tests

Integration tests are performed with the maven-invoker-plugin invoking maven projects stored in src/it.
Integration tests are bound to the verify phase of the default goal and activated using the designated its profile:

# run integration tests
$ mvn verify -Pits
# clean build prior
$ mvn clean verify -Pits
# while in development, the dev profile will make the build not fail for coverage and other enforcements  
$ mvn clean verify -Pits,dev

Integration tests are executed against a mocked Backend server.
If you need to run against the actual Backend server, use the EXHORT_ITS_USE_REAL_API environment variable:

EXHORT_ITS_USE_REAL_API=true mvn clean verify -Pits

TIP: When working on a new integration test project, it's helpful opening the IDE directly in the test project folder.

Certificate of Origin

By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the DCO file for details.