Thank you for considering contributing to CARP! We use the built-in issue tracker of GitHub for feature requests, bug reports, and general questions. Please label your issue correspondingly; the label descriptions provide guidance as to which labels to apply.
There are two permanent branches in this repository:
- develop: contains the latest code which compiles and passes all tests. Pushing to this branch results in 'SNAPSHOT' publications to Sonatype Nexus Repository. You can see whether the last snapshot was published successfully on the corresponding badge in the main README.
- master: contains the last release, as listed in releases. Pushing to this branch results in versioned Maven releases. Only maintainers of this repository can complete pull requests to master, and thus publish releases to Maven. As a maintainer, make sure you apply proper semantic versioning when incrementing version numbers.
We welcome contributions on the develop branch. Pull requests on this branch will trigger a full build and test run which needs to pass in order for the pull request to be considered. In addition, a check shows whether your changes comply with our coding conventions. We encourage you to resolve any code smells identified by detekt (visible in the output), which is ran by default as part of the build. You can also run detekt separately through gradle detekt.
Whenever adding new functionality or addressing bug fixes, try to include a unit test covering it using kotlin.test in commonTest. Unit test namespaces and classes reflect those in the main source code, so it should be self-evident where to find them/place them. Lastly, carp.test contains functionality to help write unit tests which might be useful and is imported in all test projects.
This project follows the standard Kotlin Coding Conventions, except for spacing of parentheses and braces:
- Spaces need to be added in all parentheses, except for those of higher-order functions.
- Curly braces of multi-line blocks need to be placed on separate lines (with the exception of trailing lambda arguments), aligned with the start of the definition the block is associated with (e.g., class, function, object literal, if, or return).
// Correct spacing of parentheses and curly braces.
if ( true )
{
val answer = 42
}
// Parameter parentheses of higher-order functions do not take spaces.
val higherOrder: (Int, Int) -> Int = { a: Int, _: Int -> a }
// Curly braces of trailing lambda argument defined on multiple lines are not placed on separate lines.
fun test( list: List<Int> )
{
list.forEach {
val answer = it }
}
These guidelines are checked by detekt when building the project locally, and when submitting a pull request to the develop branch. For more examples, you can look at the unit tests of the custom style rules applied by detekt.
We decided on these guidelines since research has shown that code which resembles natural language more (using spacing), leads to code which is easier to read (i.e., faster and requiring less eye fixations).