SoftwareEngineeringDoneRight-Library

Contents

• sedr-library
  • What’s included
  • Adding the dependency
  • Enforcing the justification convention with ArchUnit
  • Example project

Repository with useful and usable software components used in the Software Engineering Done Right book.

sedr-library

Shared Java annotations and utilities for Software Engineering Done Right projects.

Latest version	0.2.6
Group ID	com.arc-e-tect.sedr.utils
Artifact ID	sedr-library

What’s included

Class	Package	Description
ExcludeFromJacocoGeneratedCodeCoverage	com.arc_e_tect.sedr.utils.jacoco.marker	Marker annotation to exclude constructors, methods, or types from JaCoCo code-coverage measurement.

Adding the dependency

The library is published to GitHub Packages. Unlike Maven Central, GitHub Packages requires authentication even for public packages. You need a GitHub Personal Access Token (PAT) with the read:packages scope.

1. Store your credentials locally

Add the following to ~/.gradle/gradle.properties (create the file if it does not exist). Never commit this file — it lives outside your project.

gpr.user=<your-github-username>
gpr.key=<your-github-pat>

2. Declare the repository

Gradle (Kotlin DSL — build.gradle.kts)

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-Library")
        credentials {
            username = project.findProperty("gpr.user") as String? ?: System.getenv("GITHUB_ACTOR")
            password = project.findProperty("gpr.key") as String? ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

Gradle (Groovy DSL — build.gradle)

repositories {
    maven {
        url = uri('https://maven.pkg.github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-Library')
        credentials {
            username = project.findProperty('gpr.user') ?: System.getenv('GITHUB_ACTOR')
            password = project.findProperty('gpr.key') ?: System.getenv('GITHUB_TOKEN')
        }
    }
}

Maven (pom.xml)

<repositories>
    <repository>
        <id>github-sedr-library</id>
        <url>https://maven.pkg.github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-Library</url>
    </repository>
</repositories>

For Maven, add your credentials to ~/.m2/settings.xml:

<settings>
    <servers>
        <server>
            <id>github-sedr-library</id>
            <username>${env.GITHUB_ACTOR}</username>
            <password>${env.GITHUB_TOKEN}</password>
        </server>
    </servers>
</settings>

3. Declare the dependency

Gradle (Kotlin DSL)

dependencies {
    implementation("com.arc-e-tect.sedr.utils:sedr-library:0.3.4")
}

Gradle (Groovy DSL)

dependencies {
    implementation 'com.arc-e-tect.sedr.utils:sedr-library:0.3.4'
}

Maven

<dependency>
    <groupId>com.arc-e-tect.sedr.utils</groupId>
    <artifactId>sedr-library</artifactId>
    <version>0.3.4</version>
</dependency>

Using in CI/CD

In GitHub Actions, GITHUB_ACTOR and GITHUB_TOKEN are injected automatically — no extra secrets are needed when consuming the package from within a GitHub Actions workflow.

- name: Build
  run: ./gradlew build
  env:
    GITHUB_ACTOR: ${{ github.actor }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Enforcing the justification convention with ArchUnit

The library ships a test-fixtures artifact that contains the reusable ArchUnit rule AbstractCoverageExclusionConventionsTest. It verifies that every use of @ExcludeFromJacocoGeneratedCodeCoverage in your production code carries a non-blank justification.

Add the test-fixtures dependency

Gradle (Kotlin DSL)

dependencies {
    testImplementation(testFixtures("com.arc-e-tect.sedr.utils:sedr-library:0.3.4"))
}

Gradle (Groovy DSL)

dependencies {
    testImplementation testFixtures('com.arc-e-tect.sedr.utils:sedr-library:0.3.4')
}

The test-fixtures artifact brings archunit-junit5 and junit-jupiter-api in as transitive dependencies, so no extra entries are needed for those. You do need to add the JUnit Jupiter engine for test execution:

Gradle (Kotlin DSL)

dependencies {
    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.14.4")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

Gradle (Groovy DSL)

dependencies {
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.14.4'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

Write the convention test

Extend AbstractCoverageExclusionConventionsTest and override getBasePackage() to scope the rule to your project’s root package.

class CoverageExclusionConventionsTest extends AbstractCoverageExclusionConventionsTest {

    @Override
    protected String getBasePackage() {
        return "com.example.myapp";
    }
}

The inherited test coverageExclusionAnnotationsMustHaveJustification() runs automatically and fails if any class, constructor, or method in the scanned packages carries @ExcludeFromJacocoGeneratedCodeCoverage without a non-blank justification.

Using the annotation correctly

Compliant — justification provided

@ExcludeFromJacocoGeneratedCodeCoverage(
        justification = "Spring Boot entry point – not unit-testable")
public static void main(String[] args) {
    SpringApplication.run(MyApp.class, args);
}

Non-compliant — ArchUnit rule will fail

@ExcludeFromJacocoGeneratedCodeCoverage   // missing justification
public static void main(String[] args) {
    SpringApplication.run(MyApp.class, args);
}

Example project

A self-contained example demonstrating both compliant and non-compliant usage is located at examples/sedr-library/jacoco-marker/.

File	Purpose
src/main/java/…​/CompliantService.java	Uses @ExcludeFromJacocoGeneratedCodeCoverage with a justification — passes the rule.
src/main/java/…​/NonCompliantService.java	Uses @ExcludeFromJacocoGeneratedCodeCoverage without a justification — the ArchUnit test reports a violation for this class.
src/test/java/…​/CoverageExclusionConventionsTest.java	Extends AbstractCoverageExclusionConventionsTest targeting the example package.

To run the example (requires the library to be published to your local Maven repository first):

# 1. Publish the library locally
cd sedr-library && ./gradlew clean build publishToMavenLocal

# 2. Run the example — expected to FAIL with one ArchUnit violation
cd ../examples/sedr-library/jacoco-marker && ./gradlew test

The test run reports exactly one violation: Method NonCompliantService.stop() uses @ExcludeFromJacocoGeneratedCodeCoverage without a justification. CompliantService is not mentioned.