![NOTE] Click the Use this template button and clone it in IntelliJ IDEA.
JetBrains Academy Kotlin course template is a repository that provides a pure template to make it easier to create a new Kotlin course with the JetBrains Academy plugin (check out the Creating a repository from a template article).
The main goal of this template is to speed up the setup phase of Kotlin course development for both new and experienced educators by preconfiguring the project scaffold and CI, linking to the proper documentation pages, and keeping everything organized.
If you're still not quite sure what this is all about, read our introduction: What is the JetBrains Academy plugin?
![NOTE] Click the Watch button on the top to be notified about releases containing new features and fixes.
In this README, we will highlight the following elements of template-project creation:
- Getting started
- Gradle configuration
- Course info configuration file
- Course ignore file
- Sample code
- Adapted inspections
- Testing
- Predefined Run/Debug configurations
- Continuous integration
- Useful links
Before we dive into course development and everything related to it, it's worth mentioning the benefits of using GitHub Templates. By creating a new project with the current template, you start with no history or reference to this repository. This allows you to create a new repository easily, without copying and pasting previous content, cloning repositories, or clearing the history manually.
All you need to do is click the Use this template button (you must be logged in with your GitHub account).
The most convenient way of getting your new project from GitHub is the Get from VCS action available on the Welcome Screen, where you can filter your GitHub repository by its name.
As the last step, you need to manually review the configuration variables described in the gradle.properties file and optionally move sources from the org.jetbrains.academy.kotlin.template package to the one that works best for you.
Then you can get to work and implement your ideas.
The recommended method for Kotlin course development involves using the Gradle setup.
A course built using the JetBrains Academy Kotlin course template includes a Gradle configuration already set up.
This gradle file sets up all base dependencies and plugins for the course.
For each gradle module (each task in the course and extra modules like common as well)
it includes JUnit5 tests, Kotlin test framework, and Detekt.
It also marks the source and test folders as source- and test- source sets in the project.
The project-specific configuration file gradle.properties contains:
| Property name | Description |
|---|---|
courseGroup |
Package name. |
courseVersion |
The current version of the course in SemVer format. |
gradleVersion |
Version of Gradle used for course development. |
jvmVersion |
Version of the JVM used for course development. |
A generated JetBrains Academy Kotlin Course Template repository contains the following content structure:
.
├── .github/ GitHub Actions workflows
├── .idea/
│ └── inspectionProfiles/ Adapted inspection files
│ ├── Custom_Inspections.xml Inspection config
│ ├── profiles_settings.xml Inspection profile settings
│ └── README.md Inspection descriptions
├── .run/ Predefined Run/Debug Configurations
├── build/ Output build directory
├── gradle
│ └── wrapper/ Gradle Wrapper
├── common Course sources common for all sections
│ └── src
│ └── main
│ ├── kotlin/ Kotlin production sources
│ └── resources/ Resources - images, icons
├── courseSection/ An example of the course section
│ ├── courseLesson/ An example of the course lesson
│ │ ├── theoryTask/ An example of a theory task
│ │ │ ├── src/ Task sources
│ │ │ │ └── ...
│ │ │ ├── task.md Task/theory description
│ │ │ └── task-info.yaml Task config file
│ │ ├── quizTask/ An example of a quiz task
│ │ │ ├── src/ Task sources
│ │ │ │ └── ...
│ │ │ ├── task.md Task/quiz description
│ │ │ └── task-info.yaml Task config file
│ │ ├── programmingTask/ An example of a programming task
│ │ │ ├── src/ Task sources
│ │ │ │ └── ...
│ │ │ ├── test/ Task tests
│ │ │ │ └── ...
│ │ │ ├── task.md Task description
│ │ │ └── task-info.yaml Task config file
│ │ └── lesson-info.yaml Lesson config file
│ ├── courseFrameworkLesson/ An example of the course framework lesson
│ │ ├── ... Several examples of lessons
│ │ └── lesson-info.yaml Lesson config file
│ └── section-info.yaml Section config file
├── .courseignore Course ignoring rules
├── .gitignore Git ignoring rules
├── build.gradle.kts Gradle configuration
├── course-info.yaml Course info configuration file
├── detekt.yml Detekt configuration file
├── gradle.properties Gradle configuration properties
├── gradlew *nix Gradle Wrapper script
├── gradlew.bat Windows Gradle Wrapper script
├── LICENSE License, MIT by default
├── README.md README
└── settings.gradle.kts Gradle project settings
The course info configuration file is the course-info.yaml file located in the root directory. It provides general information about the course, like description, language, etc.
type: marketplace
title: JetBrains Academy Kotlin course template
language: English
summary: Course description
programming_language: Kotlin
content:
- courseSection
environment_settings:
jvm_language_level: JDK_17The course ignore file is the .courseignore file located in the root directory. It provides the list of files or directories that will be ignored in the final course preview or archive.
README.md
/.run
You can find more information about the course preview in the Course preview section. Information about creating a course archive and uploading it to the marketplace is in the Course distribution section.
The prepared template provides an example of a course with one section, two lessons, and five tasks in total.
Each course may have an unlimited number of sections, lessons, and tasks. Students will see almost the same course structure as the educator (course author):
The main difference is in framework lessons, which display only task files, without intermediate steps.
You can read more about framework lessons in the official documentation in the Framework Lessons Creation section.
Note
Click Course Creator -> Create Course Preview in the context menu in the root of the repository to create a course preview.
The JetBrains Academy plugin provides five different types of tasks, and you can combine them inside one lesson (whether regular or framework). You can read more about tasks in the official documentation in the Task section.
The template also includes adapted Kotlin inspections in order to provide better learning experience. This means that the IDE will highlight the most popular code issue that students encounter. To learn more about the inspections please refer to this README file.
If you don't want to use this inspections, then just delete the inspectionProfiles folder.
To check the programming exercises for edu tasks, you need to write tests. This repository includes a Kotlin test framework to make the testing process easier. It contains functionality to test student solutions by using the Java Reflection API under the hood. This approach allows you to call students' functions that do not exist yet. It is a powerful mechanism that enables you to create excesses without predefined classes or function templates and check their signature and behaviour properly.
You can find little examples of programming tasks in the repository in the Tests.kt files:
in course lesson and course framework lesson.
More examples of using the Kotlin test framework can be found in other Kotlin courses:
Within the default project structure, there is a .run directory provided, which contains predefined Run/Debug configurations that expose corresponding Gradle tasks:
| Configuration name | Description |
|---|---|
| Build course | Runs :build Gradle task with tests only. |
| Build course with detekt | Runs :build Gradle task with tests and Detekt static analysis. |
Continuous integration depends on GitHub Actions, a set of workflows that make it possible to automate your testing and release process. Thanks to such automation, you can delegate the testing and verification phases to the Continuous Integration (CI) and instead focus on development (and writing more tests).
In the .github/workflows directory, you can find definitions for the following GitHub Actions workflows:
- Build
- Builds your course
- Runs all tests for all tasks
- Build with Detekt
- Builds your course
- Runs all tests for all tasks
- Runs Detekt checks