Shiraji's Blog

How to Kontribute (V3) - Recommended Way

This blog post describes how to start Kontribute or how to start contributing Kotlin.

OK, now let’s actually work with project. There are 2 recommended ways for 1st commit of Kotlin.

  • Adding documentation or comment
  • Providing sample codes

Adding documentations or comment

Adding documentation or comment is one of best ways to start contribute any OSS including Kotlin. My first commit is also fixing URL of README

JetBrains says that they want the documentation for standard library. Find a class or a function which are not documented well from https://kotlinlang.org/api/latest/jvm/stdlib/index.html You may think there are not much function that is not documented. Trust me, you can find at least 10 undocumented functions within 1 min!

Providing sample codes

If you are not good English writer like me, then providing samples are the better way to start contributing Kotlin. https://youtrack.jetbrains.com/issue/KT-20357 is the issue for samples. This issue is especially for new Kontributors.

There are 4 steps to provide sample codes

samples-steps

Comment the target API to the issue

first_comment

Then, write sample code.

1
2
3
@Sample
fun groupBy() {
}

The method name can be anything but don’t add test as prefix/postfix because it is not test. Then add sample code inside the method.

1
2
3
4
5
6
7
8
9
10
11
12
@Sample
fun groupBy() {
    val words = listOf("a", "abc", "ab", "def", "abcd")
    val byLength = words.groupBy { it.length }

    assertPrints(byLength.keys, "[1, 3, 2, 4]")
    assertPrints(byLength.values, "[[a], [abc, def], [ab], [abcd]]")

    val mutableByLength: MutableMap<Int, MutableList<String>> = words.groupByTo(mutableMapOf()) { it.length }
    // same content as in byLength map, but the map is mutable
    assertTrue(mutableByLength == byLength)
}

There are no hard restriction for writing samples. You can add comment if it is helpful for other developers.

After that, in order to connect with sample code and target method, comment to the target method with @FQN of the sample method

1
2
3
4
5
/**
...
 * @sample samples.collections.Collections.Transformations.groupBy
 */
public inline fun <T, K> Iterable<T>.groupBy(keySelector: (T) -> K): Map<K, List<T>> {

Now, you are ready. Send Pull Request. Then, update you comment with pull request URL

first_comment2

That’s it! Easy! Now, if you want to provide the sample code, please read README for sample code, too. https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/samples/ReadMe.md

After the pull request get merged, in some point, you can see your sample code in official documentation http://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/group-by.html