Skip to content

Template repository for creating JetBrains Academy Java courses

License

Notifications You must be signed in to change notification settings

jetbrains-academy/java-course-template

Repository files navigation

JetBrains Academy Java Course Template

official project Gradle Build License: MIT

Note

Click the Use this template button and clone it in IntelliJ IDEA.

JetBrains Academy Java course template is a repository that provides a pure template to make it easier to create a new Java 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 Java 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.java.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 Java course development involves using the Gradle setup.

A course built using the JetBrains Academy Java 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. 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 Java Course Template repository contains the following content structure:

.
├── .github/                    GitHub Actions workflows
├── .run/                       Predefined Run/Debug Configurations
├── build/                      Output build directory
├── gradle
│   └── wrapper/                Gradle Wrapper
├── common                      Course sources common for all sections
│   └── src
│       └── main
│           ├── java/           Java 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
├── 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 Java course template
language: English
summary: Course description
programming_language: Java
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.

Testing

To check the programming exercises for edu tasks, you need to write tests. 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.java files: in course lesson and course framework lesson.

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.

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

Useful links

Releases

No releases published

Packages

No packages published

Languages