From d09e6cebade81d5c10226115b51e2e11ac4d8747 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Sat, 1 Mar 2025 11:16:55 +0100 Subject: add roadmap; use citations --- Makefile | 18 ++++++++++ _quarto.yml | 10 ++++++ _roadmap.qmd | 76 ++++++++++++++++++++++++++++++++++++++++ _roadmap.yml | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++ _roadmap_early.yml | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++ delivery1.qmd | 88 ++++++++++++++-------------------------------- ref.bib | 52 ++++++++++++++++++++++++++++ 7 files changed, 381 insertions(+), 63 deletions(-) create mode 100644 Makefile create mode 100644 _roadmap.qmd create mode 100644 _roadmap.yml create mode 100644 _roadmap_early.yml create mode 100644 ref.bib diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..727798f --- /dev/null +++ b/Makefile @@ -0,0 +1,18 @@ +all: preview + +render: + quarto render + +preview: + quarto preview + +lint-markdown: + @mdl --ignore-front-matter --style .mdl.rb */*.qmd */*/*.qmd + +%.svg: _%.yml + roadmap $< > $@ + +%.svg: %.puml + plantuml -pipe -tsvg < $< > $@ + +.PHONY: all preview render publish lint-markdown diff --git a/_quarto.yml b/_quarto.yml index f3f389d..a404e31 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -1,5 +1,7 @@ project: type: website + pre-render: + - make roadmap.svg roadmap_early.svg Bachelorizer.svg website: title: "Overview" @@ -21,6 +23,14 @@ monofontoptions: - Instance=Regular - Scale=0.8 +link-citations: true +bibliography: ref.bib +csl: apa +#csl: acm-sig-proceedings +#csl: chicago-fullnote-bibliography +resource-path: +- /usr/share/citation-style-language/styles + filters: - abstract-section - stylish-roles diff --git a/_roadmap.qmd b/_roadmap.qmd new file mode 100644 index 0000000..acb9bb8 --- /dev/null +++ b/_roadmap.qmd @@ -0,0 +1,76 @@ +# Task management + +This project follows kanban principles for task management, +using roadmap (described below) as a form of kanban board. + +Kanban is a japanese management method +of visually placing signs (kam) on a board (ban), +intended to to aid in breaking down a project into smaller tasks +to support team-based self-organization +[@Anderson2016, pp. xi-1]. + +Two core principles of kanban +is to maintain a visual overview of relevant tasks +and a sense of sustainability of the work on those tasks. +Commonly a two-dimensional kanban board provides overview, +with individual tasks listed vertically, +and divisions of task states horisontally, +and the even or uneven spread of tasks among divisions +is used to indicate if workload is sustainable +[@Anderson2016, pp. 7-8, 18]. + +In this project, +the tool roadmap is used for visualizing the tasks. +Reason for this choice is an interest in creating an atmosphere +supportive of creative thinking and reflective learning +rather than efficiency, +where the assembly line metaphor of conventional kanban boards +is considered counterproductive. + +Roadmap is a command-line tool +to generate a somewhat organic looking graph-based tree of tasks +from a plaintext source task list. +Roadmap takes as argument a filename for a YAML-structured list of tasks, +validates that all tasks are related as a directed acyclic graph (DAG) +with only a single end node (a tree structure), +and renders to stdout an SVG format visual diagram of the tasks. +The diagram maps out the tasks and their relationships, +with prioritized actionable tasks as green circles, +other actionable tasks as white circles, +later tasks as red pentagons, +blocked tasks as orange rectangles +and finished tasks as grey hexagons. +Each task is defined with a keyword and a label in the YAML file, +optionally adding an explicit state +of either *finished*, *ready*, *next* (meaning prioritized) or *blocked*, +and listing directly dependending task. +Task state is resolved from dependencies if not stated explicitly; +only one task, the final goal, can and must have no dependencies. +After each YAML file edit the visual diagram can be (re)generated, +which also checks +that the edited YAML contents is structurally and semantically valid. +[@Wirzenius2025]. + +For comparison with conventional kanban boards, +roadmap visualizes not as a 2-dimensional matrix +with progress as rigid lines across the x-axis +and sustainability indicated by downwards depth, +but instead visualizes as a somewhat organic looking tree structure, +with progress as neat (non-warning-colored) branches +and sustainability indicated by color saturation. + +The requirements for this project are summarized +as the following tasks: + + 1. Make a Kanban board for this assignment. + 2. Make a class diagram for the Bachelor programme and its components. + 3. Implement classes to represent the Bachelor programme and its components. + 4. Implement a method to check whether a programme is valid. + 5. Specify and run unit tests for the valid method. + +These larger tasks have been expanded and reorganized +into more smaller and narrower focused ones, +visualized in in the roadmap at @fig-kanban +as well as the early snapshot of the roadmap in @sec-kanban-early. + +![Current roadmap for this project](roadmap.svg){#fig-kanban} diff --git a/_roadmap.yml b/_roadmap.yml new file mode 100644 index 0000000..97998d3 --- /dev/null +++ b/_roadmap.yml @@ -0,0 +1,100 @@ +# Roadmap for software project Bachelorizer +# +# SPDX-License-Identifier: GPL-3.0-or-later +# SPDX-FileCopyrightText: 2025 Jonas Smedegaard +# +# @see + +goal: + label: Deliver the report + depends: + - docs_tasklist + - docs_model + - docs_structure + - docs_program + - docs_testing + +docs_tasklist: + status: ready + label: | + Document + the task list + depends: + - tasklist + +tasklist: + status: finished + label: | + Define and structure + the tasks needed + +docs_model: + status: next + label: | + Document + program model + depends: + - model + +model: + status: next + label: | + Make a class diagram + for the Bachelor programme + and its components + +docs_structure: + status: ready + label: | + Document + program structure + depends: + - structure + +structure: + status: next + label: | + Implement classes + to represent the Bachelor programme and its components + depends: + - model + +docs_program: + status: ready + label: | + Document + program + depends: + - method_validate + - testsuite + +method_validate: + label: | + Implement a method + to check whether a programme is valid + depends: + - structure + +testsuite: + label: | + Setup routines + to check unit tests + depends: + - test_validate + +test_validate: + label: | + Specify and run + unit tests for the valid method + depends: + - method_validate + +docs_testing: + status: blocked + label: | + Document results + of checking unit test + [maybe postpone for next delivery] + depends: + - structure + - test_validate diff --git a/_roadmap_early.yml b/_roadmap_early.yml new file mode 100644 index 0000000..97998d3 --- /dev/null +++ b/_roadmap_early.yml @@ -0,0 +1,100 @@ +# Roadmap for software project Bachelorizer +# +# SPDX-License-Identifier: GPL-3.0-or-later +# SPDX-FileCopyrightText: 2025 Jonas Smedegaard +# +# @see + +goal: + label: Deliver the report + depends: + - docs_tasklist + - docs_model + - docs_structure + - docs_program + - docs_testing + +docs_tasklist: + status: ready + label: | + Document + the task list + depends: + - tasklist + +tasklist: + status: finished + label: | + Define and structure + the tasks needed + +docs_model: + status: next + label: | + Document + program model + depends: + - model + +model: + status: next + label: | + Make a class diagram + for the Bachelor programme + and its components + +docs_structure: + status: ready + label: | + Document + program structure + depends: + - structure + +structure: + status: next + label: | + Implement classes + to represent the Bachelor programme and its components + depends: + - model + +docs_program: + status: ready + label: | + Document + program + depends: + - method_validate + - testsuite + +method_validate: + label: | + Implement a method + to check whether a programme is valid + depends: + - structure + +testsuite: + label: | + Setup routines + to check unit tests + depends: + - test_validate + +test_validate: + label: | + Specify and run + unit tests for the valid method + depends: + - method_validate + +docs_testing: + status: blocked + label: | + Document results + of checking unit test + [maybe postpone for next delivery] + depends: + - structure + - test_validate diff --git a/delivery1.qmd b/delivery1.qmd index 3975aaa..5a4591b 100644 --- a/delivery1.qmd +++ b/delivery1.qmd @@ -23,69 +23,31 @@ breaks: false --- -# UML Class Diagram - -```{.plantuml} -@startuml -abstract class SocketServer { - #boost::asio::io_service io_service; - #tcp::endpoint endpoint; - #tcp::iostream socketStream; - #tcp::acceptor * acceptor; - #stringstream * buffer; - - +SocketServer (string address, unsigned short port, stringstream * buf) - +~SocketServer () - +{abstract} void start () -} - -class SocketServerListener { - +void start () -} - -class SocketServerSender { - +void start () -} - -SocketServer -down-|> SocketServerListener -SocketServer -down-|> SocketServerSender - -note "Difference only in start() function" as N1 -SocketServerListener -- N1 -SocketServerSender -- N1 - - - - -abstract class SocketClient { - #tcp::iostream socketStream; - #stringstream * buffer; - #string address; - #unsigned short port; - - +SocketClient (string address, unsigned short port, stringstream * buf) - +{abstract} void start () -} - -class SocketClientListener { - +void start () -} - -class SocketClientSender { - +void start () -} - -SocketClient -down-|> SocketClientListener -SocketClient -down-|> SocketClientSender - -note "Difference only in start() function" as N2 -SocketClientListener -- N2 -SocketClientSender -- N2 - -N0 .down. SocketServer -N0 .down. SocketClient -@enduml -``` +{{< include _roadmap.qmd >}} + +# Diagram + +![UML Class Diagram](Bachelorizer.svg) + +# Code + +TODO... + +# References {.appendix} + +\begingroup +\raggedright +::: {#refs} +::: +\endgroup + +\appendix + +# Appendix 1: Early roadmap {.appendix #sec-kanban-early} + +![Early roadmap for this project](roadmap_early.svg){#fig-kanban-early} + +# Appendix 2: Program Bachelorizer {.appendix} ## Class `Bachelorizer.java` diff --git a/ref.bib b/ref.bib new file mode 100644 index 0000000..27a2e60 --- /dev/null +++ b/ref.bib @@ -0,0 +1,52 @@ +@Book{Seidl2015, + author = {Seidl, Martina and Scholz, Marion and Huemer, Christian and Kappel, Gerti}, + date = {2015}, + title = {UML @ Classroom: An Introduction to Object-Oriented Modeling}, + doi = {10.1007/978-3-319-12742-2}, + isbn = {9783319127422}, + publisher = {Springer International Publishing}, + file = {:Seidl2015 - UML @ Classroom_ an Introduction to Object Oriented Modeling.pdf:PDF}, + issn = {2197-1781}, + journaltitle = {Undergraduate Topics in Computer Science}, +} + +@Book{Goodrich2014, + author = {Goodrich, Michael T. and Tamassia, Roberto and Goldwasser, Michael H.}, + date = {2014}, + title = {Data structures and algorithms in Java}, + edition = {6. ed.}, + isbn = {9781118771334}, + location = {Hoboken, NJ}, + pagetotal = {720}, + publisher = {Wiley}, + comment = {https://annas-archive.org/md5/b70d54ea3cb636da19de5a280d3f31af}, + file = {:Goodrich2014 - Data Structures and Algorithms in Java.pdf:PDF}, + ppn_gvk = {778307271}, +} + +@Book{Anderson2016, + author = {Anderson, David J. and Carmichael, Andy}, + date = {2016}, + title = {Essential Kanban Condensed}, + isbn = {9780984521425}, + pages = {100}, + publisher = {Blue Hole Press}, + file = {:Anderson2016 - Essential Kanban Condensed.pdf:PDF}, +} + +@SoftwareVersion{Wirzenius2025, + author = {Lars Wirzenius}, + editor = {Jonas Smedegaard}, + title = {roadmap}, + url = {https://gitlab.com/larswirzenius/roadmap/}, + version = {0.7.0-3}, + date = {2025-02-07}, + publisher = {Debian}, + license = {MIT-0}, + repository = {https://salsa.debian.org/debian/rust-roadmap}, + swhid = {swh:1:rel:25f91f175f6c726bb767fc682037f6b50327ada5;origin=deb://Debian/packages/rust-roadmap;visit=swh:1:snp:e317491b4983fd4da3ddfbb7fe0375ce8c843ba5}, +} + +@Comment{jabref-meta: databaseType:biblatex;} + +@Comment{jabref-meta: fileDirectory-jonas-bastian:/home/jonas/Projects/RUC/LIB/CS-SMC2;} -- cgit v1.2.3