Preliminary final version of final report

parent beec9e41
Pipeline #108374949 passed with stages
in 8 minutes and 59 seconds
......@@ -18,19 +18,123 @@ glossary-file: glossary.tex
# Initial Situation
As mentioned in the requirements specification document our goal with tale
was not to clone git, or build a git compatible version control system.
While we were inspired by git, because it's a tool we use daily,
we did not look at the internal workings of it before or during
the project.
The goal of this project was to build our own version control system,
with enough functionality to be usable.
While we did not implement all the planned features,
the features that are present are enough for tale to be useful.
This project was not a conventional software engineering project,
but more of a research and learning project.
# Baseline Plan
To build tale we decided to use a scrum inspired process.
We created user stories for each functional requirement and divided the work
into 5 sprints.
The original user stories can be found in the requirements specification document.
The original sprint plan can be seen on the next page.
Before we started with this sprint structure,
we focused on getting the core diffing algorithm right.
More information about the algorithm can be found in chapter \ref{patchgeneration}.
During Sprint 1 we realized that we would need `tale diff` (U3)
to debug commiting (U5).
Because of this we re-arranged the stories and focused first on
delivering `tale status` (U11) and `tale diff` (U3).
We decided during Sprint 2 that undoing changes (U9) was more important
than switching between commits at will (U6, U12).
During Sprint 3 we encountered various problems with software stability
because our path handling mechanic was not well conceived.
Additional problems were faced when using reflection for JSON deserialization
and configuration handling.
More information about reflection with GraalVM Native Images can
be found in chapter \ref{nativeimages}.
Because of these problems we experienced some delays, and had to cut
out some functional requirements.
More on this in chapter \ref{functionalreqs}.
We focused the end of sprint 4 and sprint 5 on improving stability and
polishing the features that we had started.
\begin{tab}{5}{Sprint contents}{Sprint & Start Date & End Date & ID & Description}
\textbf{Sprint 1} & 2019-10-21 & 2019-11-03 & U1 & Create a repository \\ \hline
\multicolumn{3}{|c|}{} & U2 & Add contents \\ \hline
\multicolumn{3}{|c|}{} & U5 & Record changes \\ \hline
\multicolumn{3}{|c|}{} & U11 & Show status of repository \\ \hline
\textbf{Sprint 2} & 2019-11-04 & 2019-11-17 & U3 & Show differences \\ \hline
\multicolumn{3}{|c|}{} & U7 & Apply differences \\ \hline
\multicolumn{3}{|c|}{} & U10 & Show history \\ \hline
\multicolumn{3}{|c|}{} & U12 & Reset to specific commit \\ \hline
\textbf{Sprint 3} & 2019-11-18 & 2019-11-01 & U6 & Switch to a specific version/branch \\ \hline
\multicolumn{3}{|c|}{} & U9 & Undo commits \\ \hline
\textbf{Sprint 4} & 2019-12-02 & 2019-12-15 & U4 & Create new branches \\ \hline
\multicolumn{3}{|c|}{} & U8 & Merge a branch into the current one \\ \hline
\textbf{Sprint 5} & 2019-12-02 & 2019-12-15 & & Cleanup and time reserves
# Analysis
## Function Requirements
- functional requirements planned vs. actual
This chapter describes the planned requirements and whether we completed them or not.
Near the end of the project we elected not to press for new features
(P.8, P.9, P.10) but instead focus on stability and code quality.
Unfortunately this means that tale only supports linear history.
\begin{tab}{4}{Functional Requirements}{ID & Command & Description & Done}
P.1 & `init` & Create an empty repository. & Yes \\ \hline
P.2 & & Record changes in the repository. & Yes \\ \hline
P.2.1 & `add <file>` & Add file contents to the index. & Yes \\ \hline
P.2.2 & `commit` & Record changes to the repository with a message. & Yes \\ \hline
P.3 & `log` & Show past commits with different levels of detail. & Yes \\ \hline
P.4 & `diff --no-index <a> <b>` & Show difference between any two files. & Yes \\ \hline
P.5 & `diff` & Show difference between current changes and commit.& Yes \\ \hline
P.6 & `revert <commit>` & Undo a given commit. & Yes \\ \hline
P.7 & `apply <diff>` & Applies a given diff to the working tree. & Yes \\ \hline
P.8 & `branch <name>` & Creates a new branch with the given name. & No \\ \hline
P.9 & `checkout <branch or commit>` & Switches to a given branch or commit. & No \\ \hline
P.10 & `merge <branch>` & Merges the given branch into the current one. & No
## Delivery Objects
All the delivery objects generated in this module can be found on our
[GitLab Page](
The delivery objects are all built at each push using GitLab's CI feature.
\begin{tab}{3}{Delivery Objects}{Type & Name & Description}
Document & Requirement Specification & Initial document which
describes the requirement and planned process. \\ \hline
Document & Final Report & Review and summary of the project,
as well as some technical documentation \\ \hline
Documentation & JavaDoc & Generated HTML of the JavaDoc \\ \hline
Binary & tale & The compiled binary, runnable on most Linux systems.
A GraalVM Native Image. \\ \hline
Report & Java Code Coverage Report & Checks how much and what parts
of our code is covered by automated tests.
Here is an example of the code coverage report badge:
![JaCoCo Badge](assets/codecov.png){height=1em}
The full report can be found on [](
## Technical Overview
This chapter contains a technical overview of the codebase.
......@@ -90,6 +194,27 @@ We built three custom datastructures for this project:
# Lessons Learned
## Planning
### Time allocation and estimation
The main lesson we learned with regards to planning is to account for more
time to solve potential problems.
We had to cut some corners to still fit in the
minimal feature set we wanted for tale.
### User story breakdown
We had some trouble with stories depending too much on the previous
task being done.
In additon the stories were too large,
and not well suited for parallelizing the workflow.
We found it to be very easy for the work to get chaotic, because
we would realize half-way through a story that a requirement was not met yet,
which encourages going back and forth,
and having many in-progress tasks at once.
## Domain Object Model
The original plan for modeling our data and keeping it on disk can be found in
the requirement specification document.
......@@ -138,6 +263,7 @@ Our approach is error prone and not very efficient.
## Patch Generation
We attempted to design our own difference detection algorithm
and managed to cover about 70% of the cases in our test-suite,
but because this would be the foundation for tale, we decided to build our algorithm based on
......@@ -225,8 +351,14 @@ We made extensive use of the
In all we achieved a code coverage of 56%, and have covered the most important
parts of the core functionality.
### Ease of testing
We realized too late that our Command-Structure would be hard to test,
and wasted quite some time trying to built automated integration tests.
In the end we tried to modularize them as best as possible and use
traditional unit tests.
## GraalVM Native Images
[GraalVM]( is an alternative JVM/JDK based
on HotSpot/OpenJDK.
It supports polyglot programs (programs written in more than one language)
......@@ -284,18 +416,9 @@ GSON and our home made dependency injection.
# Sprint Planning
- Schedule and Tasks
## Planned
## Actual
## Differences
# Version Control
The version control is located in the
[tale-doc Repository]( on GitLab.
[tale-doc Repository]( on GitLab.
The version history of this document can be read with the following command:
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment