Skip to content

Template repository for creating JetBrains Academy Kotlin courses

License

Notifications You must be signed in to change notification settings

jetbrains-academy/kotlin-course-template

Repository files navigation

JetBrains Academy Kotlin Course Template

official project Gradle Build Gradle Build With Detekt License: MIT

![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.

Table of contents

In this README, we will highlight the following elements of template-project creation:

Getting started

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).

Use this template

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.

Use this template

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.

Gradle configuration

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.

Gradle properties

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.

Course template structure

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

Course info configuration file

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_17

Course ignore file

The 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.

Sample code

The prepared template provides an example of a course with one section, two lessons, and five tasks in total.

Course structure in the course creator mode

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):

Course structure in the course student mode

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.

Adapted inspections

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.

Testing

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:

Predefined Run/Debug configurations

Within the default project structure, there is a .run directory provided, which contains predefined Run/Debug configurations that expose corresponding Gradle tasks:

Run/Debug configurations

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

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

Useful links

Releases

No releases published

Packages

No packages published

Languages