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 three 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.
- 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.
- Grader Convert 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 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 will incur 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 so 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, lab extension 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 milestones for a delayed release or prioritized by moving them to milestones of earlier releases.
Branches for issues are created from the main branch and are merged into the main branch via a pull request when the corresponding issue has been completed. The main branch represents a consistent state of the project where each component is functional and compatible with all other components of the system.
Releases are exclusively created from the main branch and are tagged as such. From a specific tag, a Github release is created that contains the changelog of the release based on the milestone. Following the release of a minor or major version which all packages have to follow, a single release is created for all independent releases.