Comment on page
Contributing
Let's Improve Konsist Together
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.
This contributing guide is still to be polished, so feel free to start a new discussion or open an issue to discuss contributions, features/fixes, and implementation details.
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. 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.
No matter how you choose to contribute, you will be making a valuable contribution to the open-source community.
The best way to interact with the Konsist team is the dedicated #konsist-dev channel at
kotlinlang
Slack workspace.Our contributor backlog is public in JIRA. If you want to join say hello at #konsist-dev Slack channel. If you are working on a ticket make sure to get the JIRA access, assign it to yourself, and update the ticket status to In Progress).
Tickets that can be grabbed by the community have a
ContributeOpportunity
label. These are mostly tickets that are not blocking our work. You can also work on another ticket, but this will require more alignment with me, for example, certain features and planed ahead, so the ticket should be completed within a given time period.Konsist project is spread across multiple repositories:
Some of the project readmes contain Mermaid diagrams. For a diagram preview, it is recommended to install the Mermaid plugin.
This is a high-level view of project contribution:

2. Uncheck "Copy the main branch only".

3. Build the project
5. Create a new branch from the
develop
branch6. Implement changes
7. Add Tests
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.
8. Open the
Draft
Pull Request to the develop
branch (develop
will be merged into the main
branch after the release)9. Make sure all checks are passing before marking PR as
Ready for review
.For some contributors, the repo admin may have to approve checks manually for the 1st PR.
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 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
..png?alt=media)
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.
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
Maven
More
Add the following block to the
build.gradle
/ build.gradle.kts
file:repositories {
mavenLocal()
}
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>
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.
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:
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:
./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 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 thearchitectureAssert
)apiTest
- tests related toarchitectureAssert
integrationTest
- test classes using custom Kotlin snippets (.kttxt
) to test the Konsist APIkonsistTest
- tests Konsist codebase consistency usingkonsist
librarysnippets
- 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.
The high-level view of Konsist architecture:
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.The Snippetssection 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.We already have multiple community-written articles. Why not write another one? make sure to let us know if you do.
Last modified 27d ago