82 lines
3.6 KiB
Markdown
82 lines
3.6 KiB
Markdown
# coursebank
|
|
|
|
coursebank runs the assessment side of a course as version-controlled data.
|
|
Questions, exams, grading exports, and the statistics computed from them live as YAML and Parquet files in a git repository, so they can be reviewed in pull requests and tracked as each question is reused across terms.
|
|
|
|
It is both a command-line tool and a Rust library.
|
|
The command line covers the whole loop: author items, validate and lint them, assemble an exam, export it for print or Canvas, ingest the grading export, analyze it, and write the results back onto the items so the next assembly knows how each question has behaved.
|
|
|
|
## The files
|
|
|
|
A course is a directory of four kinds of file:
|
|
|
|
| Path | Holds |
|
|
|------|-------|
|
|
| `course.yaml` | course identity, policy, learning objectives, lectures |
|
|
| `banks/*.yaml` | items, with their design intent and pooled statistics |
|
|
| `assessments/*.yaml` | what was given, in what order, on what date |
|
|
| `data/*.parquet` | one row per student per item |
|
|
|
|
The first three are hand-editable YAML meant to be read in a diff.
|
|
The response data is machine-written and stored in Parquet, so pandas, polars, DuckDB, and R can read it without this tool.
|
|
|
|
## Building
|
|
|
|
coursebank builds with Rust 1.85 or newer (edition 2024).
|
|
The repository uses [pixi](https://pixi.sh) to pin the toolchain and wrap the common tasks:
|
|
|
|
```sh
|
|
pixi run build # release binary at target/release/coursebank
|
|
pixi run install # install the binary onto your PATH
|
|
pixi run tests
|
|
pixi run check # verify: formatting, lint, tests, and doc build
|
|
```
|
|
|
|
`pixi task list` prints every task with a one-line description.
|
|
|
|
Plain cargo works too with a recent toolchain:
|
|
|
|
```sh
|
|
cargo build --release
|
|
```
|
|
|
|
## Usage
|
|
|
|
Create a course, validate it, then assemble and export an exam from the pool:
|
|
|
|
```sh
|
|
coursebank init --code "BIOSC 1540" --title "Computational Biology" --term 2026s
|
|
coursebank validate
|
|
coursebank assemble exam-4 --levels 1=6,2=8,3=10,4=6 --forms 2
|
|
coursebank export typst exam-4 --form A
|
|
```
|
|
|
|
Run `coursebank --help` for the full command set.
|
|
|
|
## Versioning
|
|
|
|
Releases use calendar versioning in `YY.MM.PATCH` form.
|
|
The first release of August 2026 is `26.8.0`; a second that month is `26.8.1`; the first in September is `26.9.0`.
|
|
Neither the year nor the month is zero-padded, because the version also has to parse as SemVer and SemVer forbids leading zeros.
|
|
The number carries no compatibility promise, so treat any release as one that can change behavior and read [`CHANGELOG.md`](CHANGELOG.md) before upgrading a live course.
|
|
|
|
`pixi run bump` cuts the next version and tags it; pushing that tag publishes a release, and every push to `main` refreshes a rolling `nightly` prerelease.
|
|
The workflows live in `.gitea/workflows/`; [RELEASING.md](RELEASING.md) explains the release flow and what to configure on the Gitea side.
|
|
|
|
## License
|
|
|
|
coursebank is source-available under the [Prosperity Public License 3.0.0](LICENSE.md).
|
|
It is not an OSI-approved open-source license.
|
|
Noncommercial use is free, and the license treats educational institutions, public research organizations, government, and similar noncommercial bodies as noncommercial regardless of how they are funded.
|
|
Commercial use gets a thirty-day trial; past that it requires a commercial license.
|
|
|
|
For a commercial license, contact `licensing@scient.ing`.
|
|
|
|
Bundled dependencies keep their own licenses, reproduced in `THIRD-PARTY-LICENSES.txt` in each release.
|
|
|
|
## Contributing
|
|
|
|
If you want to contribute, open an issue first.
|
|
Contributed code will need a contributor license agreement so it can ship under both the free and the commercial license.
|
|
That agreement is not in place yet, so outside patches cannot be merged for now.
|