Contributing
Let's Improve Konsist Together
Last updated
Let's Improve Konsist Together
Last updated
So you want to help? That's great!
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 (, ). 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 channel if you do so.
No matter how you choose to contribute, you will be making a valuable contribution to the open-source community.
Our in JIRA.
The best way to interact with the Konsist team is the dedicated channel (). If you want to help or need guidelines just say hello at Slack channel.
Tickets that can be grabbed by the community have a 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.
Pick the ticket in JIRA
Assign it to yourself, and update the ticket status to In Progress
Implement the changes
Add tests (look around in codebase for similar code being tested)
Make sure all checks are passing before marking PR as Ready for review
.
Make changes
./gradlew spotlessCheck
- check the code using Spotless
./gradlew spotlessApply
- check and fix code using Spotless (if possible)
./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 🤯😉
To test the changes locally you can publish a SNAPSHOT
artifact of the Konsist to the local maven repository:
After publishing a new artifact x.y.z-SNAPSHOT
with the version number will appear in the local Maven repository:
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.
Add the following block to the build.gradle
/ build.gradle.kts
file:
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:
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
.
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
The high-level view of Konsist architecture:
Get contributor JIRA access - send your email in DM to at .
Fork repository (uncheck "Copy the main branch only")
Branch of branch
Open draft with branch as target ( branch will be merged into the branch after the release)
The - repository contains Konsist documentation (this webpage).
Fork repository
Branch of branch
Open with branch as a target
During the PR review, several types of checks are executed using (). These checks can also be executed locally using the following commands:
(runs )
Some of the project README files contain diagrams. For a diagram preview, it is recommended to install the .
The actual Konsist version is defined in the file. The SNAPSHOT
suffix will be added automatically to the published artifact.
Dependency can be added to other build systems as well. Check the section in the sonatype repository.
Konsist contains multiple custom source sets (defined by the ) to provide better isolation between various types of tests:
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 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 directory on the Konsist repository.
The repository contains this website. Create a fork of the repository, make changes using any text editor (e.g. ), and open the Pull Request targeting the main
branch.
The Snippets section requires a different approach. To ensure the snippets remain valid and aligned with Konsist API, we store them within the of the repository. With every release, new snippet pages are generated from the and placed in the GitBook 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 . class e.g. .