Repository files navigation

Hands-On labs are interactive tutorials to learn Kotlin.Each lab corresponds to one or more sample projects, and explains how to create them step-by-step.
The labs are all provided under the Apache 2.0 license and are open to contributions.

This readme provides more information on how labs are organised and is targeted at contributors.If you'd like to complete a lab, please use thewebsite.

Each labs consists of:

• Text
• Assets such as images
• Code samples

Text and assets for all labs are located under this repository under thelab-name.The sample projects corresponding to each lab are separate repositories under thehttps://github.com/kotlin-hands-on organization.

There's acommand line tool that can make the process ofinitializing everything much easier.

Each lab consists of a series of steps.Each step is represented as an individual markdown file with the naming conventionNN_{step-title} whereNN is the step number andstep-title is the step title.

Each hands-on lab should start with an00_description.md file which is the text used for the card displayed on thelist of tutorials, and a01_Introduction.md file that clearly highlights what the hands-on lab is going to cover.Ideally it should also show a screenshot of the end result (if this is for instance an application).

• Usewe (notyou) pronoun when referring to the user following the tutorial, i.e. "We first need to click on..."
• Use bold to highlight UI elements and menu entries. Use | as separators for menu entries, i.e.File|New|Project...
• Usename notation to refer to folders and files
• Use plain language. Avoid fancy and elaborate words.
• Use simple sentences. Remove words if they don’t affect the meaning.
• Use keywords that users can relate to.
• Put statements in the positive form.
• Avoid jargon and slang.
• Avoid nested structure.
• Avoid acronyms (e.g., i.e., a.k.a., etc.).
• Use Oxford comma (serial comma) - the final comma in a list of things. Example:Running, testing, and packaging.

Support modes:kotlin |js |java |groovy |xml |c |shell |swift |obj-c

`​`​`javapublicclassHelloWorld {publicstaticvoidmain(String[]args) {System.out.println("Hello, World");    }}`​`​`

Runnable modes:run-kotlin |run-kotlin-js

`​`​`run-kotlinfunmain() {println("Hello world")}`​`​`

You can use four different prompt modes:note,warning,tip,todo.

`​`​`noteLorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make.`​`​`

All assets, excluding code, should be placed in a subfolder namedassets under each lab folder.The asset should be referenced relative to this:

![](./assets/path/ImageName.png)

The following syntax allows inlining videos in the text:

![Video description](video link)

The code for the lab is located in its own repository inhttps://github.com/kotlin-hands-on organization using the naming convention{lab-name}

Please make sure you use the appropriate.gitignore file:

.gradle/gradle/*.iml.idea/build/out/.DS_Store

It should contain a README.md with the following contents:

• License (by default this would be Apache 2.0 License)
• JetBrains GitHub Label
• The following text:

This repository is the code corresponding to the hands-on lab{link to hands-on lab}.

The lab should reference the project(s) containing the source code:

You can find the code for the hands-on lab on [GitHub](https://github.com/kotlin-hands-on/{lab-name})

If the lab describes creating the project step-by-step, the state of the project after each step should be presentin the project as a separate commit. After each step, the correct commit should be referred in the text.master branchshould contain only the initial state of the project, and the final state with the complete commit history should bestored in thefinal branch.

We build sample projects on TeamCity to make sure the projects always compile.If a project contains two branches, both branches should be compiled on TeamCity.The tests in each branch should be checked automatically except special branchesthat contain failing tests for the readers to fix.

The TeamCity build configurations can be found here:

https://teamcity.jetbrains.com/project/Kotlin_HandsOnLabs?projectTab=overview&mode=builds

• Coding conventions should adapt to theKotlin Code Style.
• Packages should be namedcom.jetbrains.handson.{lab-name}

We'll be really happy to get content contributions from you!

If you want to contribute and develop a new lab, the best first step is to create an issue in this project describingyour idea to make sure something similar isn't planned already.When your idea gets approved, a new repository will be created for you where you can reference the code.

If you're not a native speaker, but want to contribute, feel free to do that.We (JetBrains) can proofread the final lab text.

Feel free to contribute small changes to existing labs directly to the corresponding projects. If you're planning on contributing more significant changes to existing labs, we recommend you get in touch with us first via an issue.