Skip to content

Latest commit

 

History

History
114 lines (72 loc) · 5.02 KB

CONTRIBUTING.md

File metadata and controls

114 lines (72 loc) · 5.02 KB
Raw

Contributing to the Kotlin Library Playground for #hacktoberfest

Before you start

If you haven't done so already, register to Hacktoberfest

==> https://hacktoberfest.digitalocean.com/

Pick up an issue

Head over to the "issues" tab and select a library for which you feel like contributing a usage sample

Issues_·_LouisCAD_kotlin-libraries-playground

For the purpose of the guide, I will assume you choose to work on Koin

Get the project to run locally

  • 🛠 Fork the project
  • ⬇️ Download the project locally
  • ⑂ Create a git branch called <LIBRARY_NAME>
  • 📁 Open the folder kotlin-jvm in IntelliJ IDEA Community or in Android Studio
  • ⌛ Wait until your IDE has configured Gradle and indexed all the thing
  • 📂 Open the file kotlin-jvm/src/main/kotlin/playground/_main.kt
  • ▶️ Run the main() function

Or, if you are fine with using the command-line:

$ git clone https://github.com/LouisCAD/kotlin-libraries-playground
$ cd kotlin-libraries-playground
$ git checkout -b <LIBRARY_NAME>
$ cd kotlin-jvm
$ ./gradlew run
> Task :run
# square/moshi - A modern JSON library for Kotlin and Java
Test: User(name=Robert, age=42)
Test: {"name":"Robert","age":42}

# (more tests)
BUILD SUCCESSFUL in 12s

Explore the other library samples

Look at the other samples for inspiration. Some notes:

  1. Put your code in a different package, but for simplicity keep it in the root playground folder, this is why we are ignoring the warning.
  2. Document what the library does and where people can find more information. People unfamiliar with the library will thank you!
  3. Put your code in a main() function so that it can be run alone. But make sure to call it from kotlin-jvm/src/main/kotlin/playground/_main.kt so that it's run when all the code is run!
  4. Document which library you are using, for when all samples are run
  5. Try to keep all your code in this single file!

kotlin-libraries-playground_–_Moshi_kt

Add the missing dependencies

Add all libraries your need in build.gradle.kts!

Note that the project is configured with gradle refreshVersions

When you want to add a new library, either

  1. You can quickly add new dependencies without leaving the IDEA, if the dependency is embedded in the plugin. Here you find the list of supported libraries
  2. If the dependency is not yet in gradle refreshVersions, use the normal Gradle syntax, but replace the version by an underscore.
dependencies {
    implementation(Square.okHttp3.okHttp)         // 1 
    implementation("org.kodein.di:kodein-di:_")   // 2
}
  1. Sync Gradle. The latest version of the library you added will be added to the file versions.properties

kotlin-libraries-playground_–___IdeaProjects_kotlin-libraries-playground_CONTRIBUTING_md_and_Kodein-DI

Later, you can update dependencies version by running the task $ ./gradlew refreshVersions

Then you simply edit the file versions.properties and Sync Gradle again.

Write your code

Here you are on your own. Well not exactly, you have the documentation of the library to follow.

Just strive to have your code both simple and meaningful

image

Avoid common mistakes

Common mistakes made in pull-requests:

  • Did your put code in his own package?
  • Did you call your sample from kotlin-jvm/src/main/kotlin/playground/_main.kt?
  • Did you reformat your code before committing? Use the action Reformat Code Alt-Cmd-L

Contribute the pull-request

  • Make sure your code is run when you run the task ./gradlew runOnGitHub. This task will be run on GitHub Actions
  • Create your pull request. Hint: there is an action for that in IntelliJ/Android Studio

What if I'm stuck?

Open the issue that was assigned to you, and describe why you are stuck. We will do our best to unstuck you :)