Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• build-logic/convention/src/main/kotlin/com/vocabri/SpotlessConfiguration.kt
• build-logic/convention/src/main/kotlin/com/vocabri/DetektConfiguration.kt
• build-logic/convention/src/main/kotlin/com/vocabri/KoverConfiguration.kt
• ProjectConventionPlugin.kt
• app/detekt-baseline.xml
• gradle/libs.versions.toml
• app/src/test/java/com/vocabri/ui/addword/MainViewModelTest.kt

Contributions to the Vocabri project are welcome. This guide provides the necessary information to get your development environment set up, understand the code quality standards, and follow the process for submitting changes. The goal is to maintain a clean, consistent, and high-quality codebase. For larger changes, it is recommended to open an issue first to discuss the proposed approach.

This guide covers setting up the project, running quality checks, the testing strategy, and the pull request workflow. Following these guidelines ensures that your contributions can be integrated smoothly.

Sources: README.md:104-111

Getting Started

Before you can contribute, you need to set up the project on your local machine.

Requirements

Ensure you have the following software installed:

• Android Studio (latest stable version is recommended)
• JDK 21

Sources: README.md:63-65, build-logic/convention/src/main/kotlin/com/vocabri/JvmVersionConfig.kt:28-28

Setup Process

1. Clone the repository and open it in Android Studio.
2. Allow Gradle to sync. This should configure the project and download all necessary dependencies.
3. You can run the app directly from Android Studio or by using the command line: ./gradlew :app:installDebug.

A google-services.json file is included in the app module for convenience. If you wish to use your own Firebase project, you must replace app/google-services.json.

Sources: README.md:69-79

Code Quality and Standards

The project enforces strict code quality standards using a combination of automated tools. These are configured via custom Gradle convention plugins in the build-logic directory. All contributions must adhere to these standards.

Sources: README.md:58-59, build-logic/convention/src/main/kotlin/ProjectConventionPlugin.kt:28-34

The following diagram illustrates the code quality toolchain applied to the project.

This diagram shows the sequence of quality gates: code is first formatted by Spotless, then analyzed by Detekt, and finally, test coverage is measured by Kover.

Code Formatting (Spotless)

Spotless is used to enforce a consistent code style across the entire codebase. It is configured to format various file types.

Sources: build-logic/convention/src/main/kotlin/com/vocabri/SpotlessConfiguration.kt:31-32

File Type	Configuration Details
Kotlin (.kt)	Formatted using ktlint. Enforces a max_line_length of 120 and applies a license header from .spotless/license-kt.
Kotlin Script (.kts)	Applies the same license header as .kt files.
XML (.xml)	Applies a license header from .spotless/license-xml.
Misc (.gradle, .md, .gitignore)	Trailing whitespace is trimmed, and files must end with a newline.
JSON (.json)	Standard JSON formatting is applied.
YAML (.yml, .yaml)	Standard YAML formatting is applied.

Sources: build-logic/convention/src/main/kotlin/com/vocabri/SpotlessConfiguration.kt:36-76

To format your code before committing, run the following command:

./gradlew spotlessApply

Sources: README.md:85-85

Static Analysis (Detekt)

Detekt is used for static code analysis to find potential bugs, code smells, and anti-patterns. The configuration is based on the default ruleset, with customizations defined in .detekt/detekt-config.yml. It also includes rules for Jetpack Compose.

Sources: build-logic/convention/src/main/kotlin/com/vocabri/DetektConfiguration.kt:39-45, gradle/libs.versions.toml:84-84

Key configuration points:

• buildUponDefaultConfig: true (extends the default Detekt config)
• autoCorrect: true (attempts to fix issues automatically)
• parallel: true (runs analysis in parallel for speed)
• Reports: Generates XML and HTML reports in build/reports/detekt/.
• Baseline: A baseline file at app/detekt-baseline.xml is used to ignore existing issues.

Sources: build-logic/convention/src/main/kotlin/com/vocabri/DetektConfiguration.kt:40-42, 52-57, app/detekt-baseline.xml

To run the static analysis checks, use the command:

./gradlew detekt

Sources: README.md:86-86

Code Coverage (Kover)

Kover is used to measure test coverage. The configuration excludes certain files and code elements from the coverage report to provide a more accurate metric of the project's business logic coverage.

Sources: build-logic/convention/src/main/kotlin/com/vocabri/KoverConfiguration.kt:31-31

The following elements are excluded from coverage reports:

• Android generated classes.
• Any code annotated with @ExcludeFromCoverage, @Composable, or @Preview.
• Specific packages like com.vocabri.ui.theme.
• Generated classes such as BuildConfig, R, and *ModuleKt.

Sources: build-logic/convention/src/main/kotlin/com/vocabri/KoverConfiguration.kt:43-62

To generate an HTML coverage report, run:

./gradlew koverHtmlReport

Sources: README.md:89-89

Build and Test

Before submitting a pull request, you must run all local checks to ensure your changes integrate correctly and meet the project's quality standards.

Testing Approach

The project uses a standard set of libraries for testing:

• Unit Tests: JUnit 4, MockK, Kotlin Coroutines Test, Robolectric.
• UI Tests: Compose UI Testing, Espresso.

Unit tests are located in the src/test directory of each module, while instrumented UI tests are in src/androidTest.

Sources: README.md:93-97, app/src/test/java/com/vocabri/ui/addword/MainViewModelTest.kt

Required Checks

The following diagram shows the workflow a contributor must follow before opening a pull request.

This flowchart outlines the mandatory local verification steps before a PR can be opened.

Sources: README.md:107-108

Here is a summary of the essential commands:

Command	Description
./gradlew spotlessApply	Automatically formats all code files.
./gradlew detekt	Runs static analysis to find code quality issues.
./gradlew test	Executes all JVM unit tests.
./gradlew :app:connectedAndroidTest	Runs instrumented UI tests on a connected device or emulator.
./gradlew koverXmlReport	Generates a code coverage report in XML format for CI.

Sources: README.md:85-90

Contribution Process

The process for contributing is a standard fork-and-pull-request model.

1. Fork the repository on GitHub.
2. Create a new feature branch from main. Keep your changes focused and incremental.
3. Make your code changes.
4. Run all local checks as described in the Build and Test section.
5. Open a Pull Request against the main branch and ensure all CI checks pass.

Sources: README.md:104-110

License

By contributing, you agree that your contributions will be licensed under the MIT License. A copy of the license is included in every source file.

Sources: README.md:113-114, app/src/main/res/values/strings.xml:2-22