Contributing

Let's Improve Konsist Together

General

So you want to help? That's great!

To chat with Konsist developers and the Konsist community please check the #konsist channel at kotlinlang Slack workspace (preferred), or start a new GitHub discussion.

The Konsist project is now at a critical stage where community input is essential to polish and mature it.

There are a variety of ways to contribute to the Konsit project:

• Coding: This is the most common way to contribute. You can fix bugs or add new features.

• Testing: You can help to improve the quality by testing the code and reporting bugs. This is a great way to get involved and help out maturing the project.

• Documentation: You can help to improve the documentation by writing or editing documentation. This is a great way to help people understand how to use Konsist.

• Community: You can answer questions or participate in discussions (GitHub, Slack). This is a great way to connect with other programmers.

• Spread the word: You can help to spread the word about the Konsist by talking about it with fellow developers. You can also write a short post or a full-fledged article. Make sure to let us know at #konsist channel if you do so.

No matter how you choose to contribute, you will be making a valuable contribution to the open-source community.

Contributing

Our contributor backlog is public in JIRA.

The best way to interact with the Konsist team is the dedicated #konsist-dev channel (kotlinlang Slack workspace). If you want to help or need guidelines just say hello at #konsist-dev Slack channel.

Tickets that can be grabbed by the community have a ContributeOpportunity label. You can also work on another improvement or bug-fix, but this may require more alignment, for example, certain features and planned ahead, so the ticket should be completed within a given time period.

Start Contributing - Konsist

1. Get contributor JIRA access - send your email in DM to #igorwojda at kotlinlang Slack workspace.

2. Pick the ticket in JIRA

3. Assign it to yourself, and update the ticket status to In Progress

4. Fork Konsist repository (uncheck "Copy the main branch only")

1. Branch of develop branch

2. Implement the changes

3. Add tests (look around in codebase for similar code being tested)

4. Open draft Pull Request with develop branch as target (develop branch will be merged into the main branch after the release)

   1. Make sure all checks are passing before marking PR as Ready for review.

Start Contributing - Konsist Docs

The konsist-documentation - repository contains Konsist documentation (this webpage).

1. Fork Konsist-documentation repository

2. Branch of main branch

3. Make changes

4. Open new Pull Request with main branch as a target

Checks

During the PR review, several types of checks are executed using GitHub Actions (.github/workflow). These checks can also be executed locally using the following commands:

• Spotless (runs ktlint)

  • ./gradlew spotlessCheck - check the code using Spotless

  • ./gradlew spotlessApply - check and fix code using Spotless (if possible)

• Detekt

  • ./gradlew detektCheck - check the code using Detekt

  • ./gradlew detektApply - check and fix code using Detekt (if possible)

• Tests

  • ./gradlew lib:test - run JUnit tests

  • ./gradlew lib:apiTest - run API tests

  • ./gradlew lib:integrationTest - run integrations tests

  • ./gradlew lib:konsistTest - run Konsist tests to test Konsist codebase 🤯😉

Konsist adheres to stringent testing standards. Each Provider undergoes testing against every type of declaration, leading to an extensive set of tests. This thorough testing ensures two main objectives:

1. Guaranteeing future compatibility with Kotlin 2.0.

2. Due to reliance on an external library for parsing, it's imperative to have comprehensive tests to ensure the Konsist API functions as anticipated.

IntelliJ IDEA Plugins

Some of the project README files contain Mermaid diagrams. For a diagram preview, it is recommended to install the Mermaid plugin.

Testing Changes Locally

Publish Konsist Artifact To Local Maven Repository

To test the changes locally you can publish a SNAPSHOT artifact of the Konsist to the local maven repository:

./gradlew publishToMavenLocal -Pkonsist.releaseTarget=local

After publishing a new artifact x.y.z-SNAPSHOT with the version number will appear in the local Maven repository:

Mac: /Users/<user_name>/.m2/repository/com/lemonappdev/konsist
Windows: C:\Users\<User_Name>\.m2\repository\com\lemonappdev\konsist
Linux: /home/<User_Name>/.m2/repository/com/lemonappdev/konsist

The actual Konsist version is defined in the gradle.properties file. The SNAPSHOT suffix will be added automatically to the published artifact.

To use this artifact you have to add a local Maven repository to your project.

Use Published Artifact From Local Maven Repository

Every project contains a list of the repositories used to retrieve the dependencies. A local Maven repository has to be manually added to the project.

Gradle

Add the following block to the build.gradle / build.gradle.kts file:

repositories {
    mavenLocal()
}

Maven

By default, the Maven project uses a local repository. If not add the following block to the module\pom.xml file:

<repositories>
    <repository>
        <id>local</id>
        <url>file://${user.home}/.m2/repository</url>
    </repository>
</repositories>

More

Dependency can be added to other build systems as well. Check the snippets section in the sonatype repository.

Now build scripts will use the local repository to resolve dependencies, however, the version of Konsist has to be updated to the SNAPSHOT version of the newly published artifact e.g.

com.lemonappdev:konsist:0.12.0-SNAPSHOT

Now build scripts will be able to resolve this newly published Konsist artifact.

Verify Used Konsist Artifact Version

IntelliJ IDEA UI provides a convenient way to check which version of Konsist is used by the project. Open the External Libraries section of Project view and search for Konsist dependency:

No Matching Toolchains Found Error

If during a build you encounter an error regarding No matching toolchains found then open Module Settings / Project Structure windows and set Java SDK to version e.g. 19.

You can install missing JDKs directly from IntelliJ IDEA - click on the Module SDK combo box and select +Add SDK.

If during the build you encounter an error regarding Could not determine the dependencies of null. then open File / Settings / Build, Execute, Deployment / Build Tools / Gradle window and set Java SDK to version 19.

Architecture

Source Sets

Konsist contains multiple custom source sets (defined by the JVM Test Suite Plugin) to provide better isolation between various types of tests:

• test - tests related to generic Konsist API (everything except the architectureAssert)

• apiTest - tests related to architectureAssert

• integrationTest - test classes using custom Kotlin snippets (.kttxt) to test the Konsist API

• konsistTest - tests Konsist codebase consistency using konsist library

• snippets - contains Kotlin code snippets, written as methods (tests without @Test annotation), so the tests are not executed. These snippets are used to generate documentation. The update-snippets.py script generates PR to update the snippets page

We aim to test the majority of aspects within these source sets. However, certain kinds of checks require a dedicated test project. These projects are available in the test-project directory on the Konsist repository.

Layers

The high-level view of Konsist architecture:

Make a Change In The Konsist Documentation Repository

The konsist-documentation repository contains this website. Create a fork of the repository, make changes using any text editor (e.g. Visual Studio Code), and open the Pull Request targeting the main branch.

Updating Snippets

The Snippets section requires a different approach. To ensure the snippets remain valid and aligned with Konsist API, we store them within the snippet source set of the konsist repository. With every release, new snippet pages are generated from the snippet source set and placed in the GitBook documentation (konsist-documentation repository).

Some snippets depend on classes/interfaces/annotations from external frameworks such as Spring Repository annotation or Android ViewModel class. To avoid coupling Konsist with these frameworks and allow snippet compilation, we store placeholder classes mimicking the full names of the external framework in this directory. class e.g. Inject.kt.