This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Work in Progress

Currently under development.

1 - 📝 Notes

Notes for Divekit development

2024-10-01 Stefan, Torben (via Discord)

divekit patch

  • Individual files are passed to the command
  • Local testing is important for verification
  • Variables are also replaced during patching
  • Files are currently patched individually (can also be done in one commit)

divekit distribute

  • Not push because:
    • git push
      • Performs consistency checks (merge needed, missing pulls)
      • There are differences between Origin and Remote (variables)
      • The target is not the client but a creation operation within the server (?)

2024-09-12 Stefan, Fabian, Torben (in Person)

config

  • Distribution “test” -> “supervisor” -(later)-> “sandbox”
  • Distribution “code” -> “student”

divekit doctor

  • move to another “error control” command?
  • execute before other appropriate commands and possibly abort

divekit install

  • Possibly look into open source to see how others do it
  • Offer executables, divekit install copies the/an executable into the home directory and writes the path to the divekit executable in the PATH (and an update executable?).
  • divekit install, which copies divekit into the user directory and adds the divekit path to the PATH (and maybe already prepares all the doctor preparations)

divekit init

  • Merge with members for latecomers
  • Also update overview (new members missing)
  • Re-running ensures everything is in place

2024-09-12 Stefan, Fabian, Torben (in person)

divekit doctor

  • move to another “error control” command?
  • execute before other appropriate commands and possibly abort

divekit distribute

  • push -> create?
  • push -> distribute! (favorite)

2 - Config Redesign

Documentation of the configuration system redesign for DiveKit. This page describes the current state, planned changes, and future configuration structure.

Current State

ARS

RepoEditor (-> PatchTool)

OriginRepo

Assigned Configurations

[0] INIT

Configurations that typically only need to be defined once during installation.

Optimally in: {$HOME}/.divekit/

[1] SEMESTER

Configurations that typically only need to be defined once per semester. They are best stored in the OriginRepo.

Optimally in: {OriginRepo}/.divekit_norepo/{distribution}/

[2] MILESTONE

Configurations that typically only need to be defined once per milestone. They are best stored in the OriginRepo.

Optimally in: {OriginRepo}/.divekit_norepo/{distribution:{milestone}}/

[3] CALL

Configurations that must be defined with each call.

Optimally in: CLI flags

Future

[0] INIT

{ARS}/.env will be stored in {$HOME}/.divekit/

ACCESS_TOKEN=YOUR_ACCESS_TOKEN
HOST=https://git.st.archi-lab.io
BRANCH=main

{ARS}/originRepositoryConfig.json -> {$HOME}/.divekit/origin.json

Will be stored here during installation and then copied to the new Origin Repos during divekit init.

{
    "variables": {
        "variableDelimiter": "$"
    },
    "solutionDeletion": {
        "deleteFileKey": "//deleteFile",
        "deleteParagraphKey": "//delete",
        "replaceMap": {
            "//unsup": "throw new UnsupportedOperationException();",
            "//todo": "// TODO"
        }
    },
    "warnings": {
        "variableValueWarnings": {
            "typeWhiteList": ["json", "java", "md"],
            "ignoreList": ["name", "type"]
        }
    }
}

Suggested change:

{
    "version": "2.0",
    "variables": {
        "delimiter": "$"
    },
    "solutionCleanup": {
        "deleteFile": "//deleteFile",
        "replaceParagraph": {
            "//unsup": "throw new UnsupportedOperationException();",
            "//todo": "// TODO",
            "//delete": null
        }
    },
    "warnings": {
        "variation": {
            "fileTypes": ["json", "java", "md"],
            "ignore": ["name", "type"]
        }
    }
}

{ARS}/relationsConfig.json -> {$HOME}/.divekit/variation/relations.json

Will be stored here during installation and then copied to the new Origin Repos during divekit init.

[!NOTE]
I don’t fully understand what this is for - it may remain here forever and not need to be copied to the Origin Repo?
(what is UmletRev? What does the star mean?)

[
    {
        "id": "OneToOne",
        "Umlet": "lt=-\nm1=1\nm2=1",
        "UmletRev": "lt=-\nm1=1\nm2=1",
        "Short": "1 - 1",
        "Description": "one to one"
    },
    {
        "id": "OneToMany",
        "Umlet": "lt=-\nm1=1\nm2=*",
        "UmletRev": "lt=-\nm1=*\nm2=1",
        "Short": "1 - n",
        "Description": "one to many"
    },
    {
        "id": "ManyToOne",
        "Umlet": "lt=-\nm1=*\nm2=1",
        "UmletRev": "lt=-\nm1=1\nm2=*",
        "Short": "n - 1",
        "Description": "many to one"
    },
    {
        "id": "ManyToMany",
        "Umlet": "lt=-\nm1=*\nm2=*",
        "UmletRev": "lt=-\nm1=*\nm2=*",
        "Short": "n - m",
        "Description": "many to many"
    }
]

Suggested change:

  • id->key ?
{
    "version": "2.0",
    "relations": [
        {
            "id": "OneToOne",
            "umlet": "lt=-\nm1=1\nm2=1",
            "umletRev": "lt=-\nm1=1\nm2=1",
            "short": "1 - 1",
            "description": "one to one"
        },
        {
            "id": "OneToMany",
            "umlet": "lt=-\nm1=1\nm2=*",
            "umletRev": "lt=-\nm1=*\nm2=1",
            "short": "1 - n",
            "description": "one to many"
        },
        {
            "id": "ManyToOne",
            "umlet": "lt=-\nm1=*\nm2=1",
            "umletRev": "lt=-\nm1=1\nm2=*",
            "short": "n - 1",
            "description": "many to one"
        },
        {
            "id": "ManyToMany",
            "umlet": "lt=-\nm1=*\nm2=*",
            "umletRev": "lt=-\nm1=*\nm2=*",
            "short": "n - m",
            "description": "many to many"
        }
    ]
}

{ARS}/variableExtensionsConfig.json -> {$HOME}/.divekit/variation/variableExtensions.json

Will be stored here during installation and then copied to the new Origin Repos during divekit init.

[
    {
        "id": "Basic",
        "variableExtensions": {
            "": {
                "preValue": "",
                "value": "id",
                "postValue": "",
                "modifier": "NONE"
            },
            "Class": {
                "preValue": "",
                "value": "id",
                "postValue": "",
                "modifier": "NONE"
            },
            "Package": {
                "preValue": "",
                "value": "Class",
                "postValue": "",
                "modifier": "ALL_LOWER_CASE"
            },
            "ClassPath": {
                "preValue": "thkoeln.st.st2praktikum.racing.", // ??? deprecated ???
                "value": "Class",
                "postValue": ".domain",
                "modifier": "ALL_LOWER_CASE"
            }
        }
    },
    {
        "id": "Getter",
        "variableExtensions": {
            "GetToOne": {
                "preValue": "get",
                "value": "Class",
                "postValue": "",
                "modifier": "NONE"
            },
            "GetToMany": {
                "preValue": "get",
                "value": "s",
                "postValue": "",
                "modifier": "NONE"
            }
        }
    }
]

Questions

From my notes

I thought I had written this somewhere already, but I can’t find it anymore.

  • [0] INIT -> “Installation” exists twice
    • Once during DiveKit installation
    • Once during DiveKit initialization in a new OriginRepo

So what should go where (have ideas)?

  • Is the preValue still needed?
    I unfortunately don’t remember exactly what/why, but this was causing some significant issues.

3 - Deployment

How to deploy and release new versions of Divekit.

[!WARNING]
Not implemented this way yet - the current process is shown in the gif below.

This guide covers the process of deploying and releasing new versions of Divekit.

Version Management

Semantic Versioning

Divekit follows Semantic Versioning:

  • MAJOR version for incompatible API changes
  • MINOR version for new functionality
  • PATCH version for bug fixes

Version Tagging

# Current version is v2.0.0

# Bump patch version (e.g., v2.0.0 -> v2.0.1)
./deploy.sh patch

# Bump minor version (e.g., v2.0.0 -> v2.1.0)
./deploy.sh minor

# Bump major version (e.g., v2.0.0 -> v3.0.0)
./deploy.sh major

# Create alpha/beta versions
./deploy.sh minor -alpha.1  # Creates v2.1.0-alpha.1
./deploy.sh patch -beta.2   # Creates v2.0.1-beta.2

# Rollback options
./deploy.sh rollback        # Removes current tag and returns to previous version
./deploy.sh rollback v2.1.0 # Removes specific version tag

Example (current state)

Versioning

Release Process

  1. Update version using deploy.sh:
./deploy.sh <patch|minor|major> [-alpha.N|-beta.N]
  1. Update CHANGELOG.md:
## [2.0.1] - YYYY-MM-DD

### Added
- New feature X
- Command Y support

### Changed
- Improved Z performance

### Fixed
- Bug in command A
  1. Create release branch:
git checkout -b release/v2.0.1
  1. Build and test locally:
go test ./...
go build
  1. Create GitLab release:
  • Tag version is created automatically
  • Changelog from CHANGELOG.md is included automatically
  • CI pipeline automatically:
    • Runs all tests
    • Builds binaries for all supported platforms
    • Creates release artifacts
    • Uploads binaries to the release

Deployment Checklist

  • All tests passing locally (go test ./...)
  • Documentation updated
  • CHANGELOG.md updated
  • Version tagged using deploy.sh
  • GitLab CI/CD Pipeline completed successfully:
    • Binaries built successfully
    • Release artifacts generated
  • Release created and verified in GitLab
  • Generated binaries tested on sample installation

Rollback Procedure

If issues are found:

  1. Execute rollback using deploy.sh:
./deploy.sh rollback [version]  # Version is optional

This automatically executes the following steps:

  • Deletes the specified tag (or current tag if no version specified) locally and remote
  • Reverts to the previous version
  • Creates a new hotfix branch if desired

Examples:

./deploy.sh rollback          # Removes the most recent tag
./deploy.sh rollback v2.1.0   # Removes specific version v2.1.0
./deploy.sh rollback v2.0.0-alpha.1  # Removes a specific alpha version

If manual rollback is necessary:

git tag -d v2.0.1
git push origin :refs/tags/v2.0.1
git checkout -b hotfix/2.0.2