Home
Welcome to the Developer Guide for Grader Service!
Developer Guide provides developers with comprehensive software information, which they utilize to understand, develop and interact with Grader Service.
Grader Service offers lecturers and students a well-integrated teaching environment for data science, machine learning and programming classes.
The application consists of two main components:
-
Grader Service provides REST endpoints to create, read, update, delete and grade assignments. It also integrates a git service from which lecturers can pull and push to collaborate on the assignment creation and store student submissions. The Grader Service package also includes Grader Convert, which implements the generation of gradable notebooks, automatic grading of said notebooks and creation of feedback files and is a dependency of both the service and the extension.
-
Grader Labextension implements a front-end view for students, tutors and instructors as well as a server extension that functions as a middleware between frontend and backend. Users can access the complete functionality of the grader service through the widgets and input extensions. Additionally, it handles the local file system and repositories on the spawned JupyterHub servers to create, delete, pull and push files or directories. It is located in its own repo.
Grader service uses a loose variant of semantic versioning (SEMVER) to govern API compatibility and version numbering.
Grader service release numbers are made up of MAJOR.MINOR.PATCH. Due to the involvement of three packages in semantic versioning, special consideration has gone into implementing versioning for the grader service.
The API to base the versioning on is defined by the REST API of the Grader Service and the output schema of Grader Convert. Any backward-incompatible change to the REST API of the Grader Service incurs a breaking change to the overall API. Furthermore, Grader Convert defines a secondary API where any backward-incompatible change in the schema of the output of Grader Convert (JSON files) will also lead to breaking changes in the API.
Note
Changes in the REST API between the frontend and Labextension backend are encapsulated in a single package and do not affect the overall API.
In the initial development phase (versions 0.y.z), PATCH versions are incremented when bug fixes and API backward-compatible features are introduced. MINOR versions MUST be incremented if any breaking API changes are introduced. MINOR versions MAY be incremented if substantial new functionality or improvements are introduced.
Following the public release (versions 1.0.0 and above), PATCH versions are incremented when bug fixes are introduced. MINOR versions MUST be incremented if backward-compatible features or functionality are introduced. MAJOR versions MUST be incremented if any breaking API changes are introduced.
In the initial development phase (versions 0.y.z), the packages are compatible if their minor versions match. For example, lab extension release 0.4.13 is compatible with grader service release 0.4.2 and incompatible with Grader Service release 0.5.0.
Following the public release (versions 1.0.0 and above), the packages are compatible if their major versions match. For example, Labextension release 1.4.13 is compatible with grader service release 1.1.2 and incompatible with Grader Service release 2.0.0.
Grader service follows no fixed release schedule. Releases are tracked with milestones to which relevant issues are assigned. All issues assigned to a milestone have to be completed before a release is made. Issues can be moved to later milestones for a delayed release or prioritized by moving them to milestones of earlier releases. If an issue is being worked on, it has to be assigned to a milestone. Otherwise, it can also have no milestone (backlog).
Branches for issues are created based on the main branch and are merged into the release branch of the corresponding milestone via a pull request when the issue has been completed. The name of a release branch has to start with release- followed by the name of the milestone. The main branch represents a consistent state of the project where each component is functional and compatible with all other components of the system.
Before a release, the branch of that release gets merged into main. Releases are exclusively created from the main branch and are tagged as such. From a specific tag, a Github release is created which triggers the necessary publish actions. This Github release contains the changelog of the corresponding milestone.
When a release is made, the appVersion of the Helm Chart is automatically updated. To release the new version in the helm package, the chart release version has to be incremented as well.
Grader Service uses tbump to manage the version numbers of all packages. In the directory of the respective package (grader_convert, grader_service, or grader_labextension) you can check the current version of the package by running the following command:
tbump current-versionTo change the version number run:
tbump <new-version>As an example we want to create a new release with version 1.5.3 of Grader Service. We know we want to also create a chart release so we first increment that without without creating a tag (--no-tag):
cd charts/grader-service
tbump 1.2.0 --no-tagNote
The Chart version can be different from the Grader Service version!
We can now update the Grader Service version:
cd ../..
tbump 1.5.3This will automatically do two things: change the version in all the necessary files and create and push a git tag with the correct name. Based on this git tag a GitHub release can be created.