add validity chapter to pf1

1 files changed, 107 insertions, 0 deletions

diff --git a/portfolio1.md b/portfolio1.md
index e69de29..8e59c1f 100644
--- a/portfolio1.md
+++ b/portfolio1.md
@@ -0,0 +1,107 @@
+# Task management
+
+Bachelorizer 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 visually present an overview of tasks
+as a way of identifying them,
+and
+associating tasks with a progress state
+as a way of managing flow of progress.
+Commonly a two-dimensional kanban board provides overview,
+with individual tasks listed vertically
+and divisions of task states horisontally
+[@Anderson2016, p. 18].
+One of the aims of these principles is
+to establish a sense of sustainability
+in the pace of working on the tasks involved in a project
+[@Anderson2016, pp. 7-8].
+
+With Bachelorizer,
+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,
+for which 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 the first portfolio delivery for Bachelorizer
+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 Bachelorizer](roadmap.svg){#fig-kanban}
+
+## Validity of bachelor programmes
+
+The isValid() function in the Programme class
+currently works by checking which type an activity has based on
+the result of activity.toString().
+It simply runs through every activity and adds 1 to a counter for each category.
+It calculates ECTS based on getEcts() for each activity,
+originally supplied by a long list of object declarations in the Main class.
+This could very well be integrated with the database to get more and accurate
+information about each activity,
+but time pressure has prevented us from this implementation,
+even though the project structure easily allows it.
+The expected values for count and total ECTS for validation supplied
+by the assignment description is then validated in a simple return statement.
+
+The unit tests simply create example programmes similar to what is done in main
+and then calls the isValid() function to compare to expected values.
+Other unit tests could explore edge cases.
+For example,
+the current structure of the classes does not truly differentiate between
+the subject modules that activities are part of,
+so it has no way of enforcing that subject module activities
+are part of exactly 2 subject modules.
+Another implementation that could pass such a unit test would need
+each activity to have an attribute describing which subject module it is part of.