Quick Start

• 1: Hello there 👋
• 2: Installation
• 3: 🚧 Individualization
• 4: Distribution
• 5: Glossary

1 - Hello there 👋

What is Divekit?

Divekit is a command-line tool for managing individualized programming assignments at scale. It helps educators create, distribute and evaluate programming exercises for large groups of students.

Key Features

• Assignment Individualization: Generate unique variations of programming assignments for each student
• Automated Distribution: Create and manage GitLab repositories for students automatically
• Test Integration: Built-in support for automated testing and evaluation
• Bulk Operations: Efficiently manage assignments for large classes
• Access Control: Manage repository access rights and permissions

Benefits

• Prevent Plagiarism: Each student receives a slightly different version of the assignment
• Save Time: Automate repetitive tasks like repository setup and access management
• Ensure Fairness: Standardized testing and evaluation across all variations
• Scale Easily: Handle large classes with minimal additional effort

Use Cases

Divekit is primarily used in educational settings where:

• Programming assignments need to be distributed to many students
• Each student should receive an individualized version
• Automated testing and evaluation is desired
• Manual administrative overhead should be minimized

The tool consolidates functionality that was previously spread across multiple separate tools into a single, easy-to-use CLI application.

Divekit is a toolkit for managing individualized programming assignments at scale.

Who needs Divekit?

Divekit is designed for different stakeholders in programming education:

Course Instructors

Primary users who:

• Create and manage programming assignments
• Need to distribute exercises to large groups of students
• Want to prevent plagiarism through individualization
• Need efficient ways to evaluate student submissions

Benefits

• Automated repository management
• Built-in individualization system
• Integrated testing capabilities
• Bulk operations for large classes

Teaching Assistants

Support staff who:

• Help manage student repositories
• Assist with assignment evaluation
• Provide technical support to students

Benefits

• Standardized repository structure
• Automated access management
• Consistent testing environment
• Clear overview of student progress

Students

End users who:

• Receive individualized assignments
• Submit their solutions through Git
• Get automated feedback on their work

Benefits

• Personal GitLab repositories
• Immediate feedback through automated tests
• Clear assignment structure
• Consistent submission process

Why Divekit?

How Divekit works

2 - Installation

Prerequisites

Before installing Divekit, ensure your system meets the following requirements:

System Requirements

• Operating System: Linux, macOS, or Windows
• GitLab: Access to a GitLab instance with API permissions

GitLab Setup

1. Access to a GitLab instance
2. Admin rights to create groups and repositories
3. Personal Access Token with api scope

Creating a Personal Access Token

1. Create one here

or

1. Navigate to your GitLab profile settings
2. Go to “Access Tokens”
3. Create a new token with required scopes
4. Save the token securely - you’ll need it during installation

Storage Requirements

• Minimum 1GB free disk space
• Additional space for repositories (varies by project size)

Network Requirements

• Stable internet connection
• Access to GitLab API endpoints
• No blocking firewalls for HTTP requests

Optional Requirements

• Docker: For running tests in containers
• Maven/Gradle: For Java project support
• IDE: Any Git-compatible IDE for development

Installation

1. Download the latest release:

   • Navigate to Divekit CLI Releases
   • Download a built version for your operating system

2. Install Divekit:
   Navigate to the download directory and run the installation script:

./divekit.exe install  # On Windows
./divekit install      # On Linux/macOS

Environment Setup

After installation, you need to configure your GitLab token in your system’s environment variables. There are two methods available:

Recommended Method: System Environment Variables

Windows

1. Open System Properties > Advanced > Environment Variables
2. Add a new User Variable:
   • Variable name: GITLAB_TOKEN
   • Variable value: <YOUR_TOKEN>
3. Restart your terminal

Linux

Add to your ~/.bashrc or ~/.zshrc:

export GITLAB_TOKEN="<YOUR_TOKEN>"

Then run:

source ~/.bashrc  # or source ~/.zshrc

macOS

Add to your ~/.zshrc:

export GITLAB_TOKEN="<YOUR_TOKEN>"

Then run:

source ~/.zshrc

Alternative Method (Not Recommended)

You can store the token in a .env file in the Divekit configuration directory:

# In ~/.divekit/.env
GITLAB_TOKEN=<YOUR_TOKEN>

⚠️ Warning: This method is not recommended as the token is stored unencrypted and poses a potential security risk. Prefer using system environment variables instead.

To improve security when using this method:

# Restrict file permissions (Linux/macOS)
chmod 600 ~/.divekit/.env

This ensures only the file owner of your account (you) can read and write the file.

Verify Installation

Run the doctor command to verify your setup:

divekit doctor

This will check if:

• Divekit is properly installed
• Required environment variables are set
• System requirements are met

Troubleshooting

If you encounter any issues:

1. Check if the GitLab token is correctly set in your environment variables
2. Run divekit doctor for detailed diagnostics
3. 🚧 Check the logs in ~/.divekit/logs
4. Ensure you have the correct permissions for the installation directory

First Steps After Installation

Create Your First Assignment

1. Create and navigate to a new directory:

mkdir my-assignment
cd my-assignment

2. Initialize a new Divekit project:

divekit init

Assignment Content Creation

1. Add your assignment files to the repository
2. Mark solution parts in your code:

public class Example {
    //unsup
    return actualSolution;
    //unsup
}

3. Add variables for individualization:

public class $EntityClass$ {
    // ...
}

Assignment Distribution

1. Verify your setup:

divekit doctor

2. Distribute the repositories:

divekit distribute

Next Steps

For more detailed information, please refer to:

• Configuration options in the Configuration section
• Detailed system requirements in the Prerequisites section

3 - 🚧 Individualization

Overview

Divekit allows you to create individualized programming assignments for each student. This is done by defining variables that are populated with random values during the repository generation.

Variable Types

There are three types of variables:

1. Object Variables

Object variables are used to randomize entities and value objects. They are defined in the configuration file {ORIGIN_REPO}/.divekit/variables/variations.json:

{
  "ids": "Vehicle",
  "objectVariations": [
    {
      "id": "Car",
      "Class": "Car", 
      "RepoClass": "CarRepository",
      "SetToOne": "setCar",
      "SetToMany": "setCars"
    },
    {
      "id": "Truck",
      "Class": "Truck",
      "RepoClass": "TruckRepository",
      "SetToOne": "setTruck", 
      "SetToMany": "setTrucks"
    }
  ],
  "variableExtensions": ["Getter"]
}

2. Relation Variables

Relation variables define relationships between entities. They are defined by two components:

1. Relationship types in {ORIGIN_REPO}/.divekit/variables/relations.json:

{
  "id": "OneToOne",
  "Umlet": "lt=-\nm1=1\nm2=1",
  "Short": "1 - 1",
  "Description": "one to one"
}

1. Concrete relationships in the variations.json:

{
  "relationShips": [
    {
      "id": "Rel1",
      "relationType": "OneToOne"
    }
  ],
  "relationObjects": [
    {
      "id": "RelVehicleWheel",
      "Obj1": "Vehicle",
      "Obj2": "Wheel" 
    }
  ]
}

3. Logic Variables

Logic variables allow the definition of different business logic variants. Files can be suffixed with _LogicId and will only be included if this logic variant is selected:

{
  "id": "VehicleLogic",
  "logicVariations": [
    {
      "id": "VehicleCrash",
      "Description": "Implementieren Sie die Crash-Logik..."
    },
    {
      "id": "VehicleShop", 
      "Description": "Implementieren Sie die Shop-Logik..."
    }
  ]
}

Using Variables

Variables can be referenced in files with a configurable delimiter (default: $):

public class $VehicleClass$ {
    // ...
}

For each variable, three variants are automatically generated:

• Original: VehicleClass -> MonsterTruck
• First letter lowercase: vehicleClass -> monsterTruck
• All lowercase: vehicleclass -> monstertruck

Persistence

The generated individual variables are stored in the distribution under {ORIGIN_REPO}/.divekit/{DISTRIBUTION_NAME}/individual_repositories.json and can be reused if needed.

Quality Assurance

Divekit can issue warnings if suspicious values remain after variable replacement (e.g., “Car” in a Truck variant). This helps to identify accidentally unmodified variables.

4 - Distribution

Overview

Divekit can distribute your assignment to multiple repositories on GitLab, creating individualized versions for each student or group. This process includes:

• Creating code repositories for each student/group
• Optionally creating test repositories
• Assigning the correct permissions to students
• Individualizing the content based on your configuration

Distribution Guide

Simply use the distribute command to start the distribution process:

divekit distribute

The command will:

1. Ask you to select a distribution if multiple are configured
2. Check if all configured members exist on GitLab
3. Show you a summary of what will be created
4. Create the repositories after your confirmation

Example Flow

$ divekit distribute

? Found several distributions. Please choose one:
[ ] local
[x] supervisor
[ ] student

Checking members:
[√] 2 users available 
[X] 3 users not found:
    - ada
    - charles
    - jobs

Would create 2 repositories with name "ST2-2024-{uuid}" and assign 2 members.

? Continue? [Y/n]: y

Creating main repositories at #234567:
[██████████████████████████████████████████████████] 100% (2/2)

Creating test repositories at #345678:
[██████████████████████████████████████████████████] 100% (2/2)

Assigning members:
[███████████████████████████                         ] 50% (1/2)

What Happens During Distribution?

1. Divekit creates a new repository for each student/group
2. If configured, test repositories are created separately
3. Repository contents are individualized based on your configuration
4. Students are assigned with appropriate permissions
5. Each repository gets a unique identifier

Next Steps

• Learn more about configuration options
• Understand how to individualize assignments
• Check the CLI commands reference for advanced options

5 - Glossary

This glossary provides definitions for terms used throughout the Divekit documentation.