document first milestone

The milestone explains the goal for the current period of work. This
keeps me focused on that goal and avoids scope creep.

Author: arnemertz

docs/_config.yml

@@ -38,6 +38,7 @@ show_excerpts: true
 header_pages:
   - _pages/frontpage.md
   - _pages/about.md
+  - _pages/milestones.md
   - _pages/archive.md
 
 include:

docs/_pages/milestones.md

@@ -0,0 +1,36 @@
+---
+permalink: /milestones
+layout: page
+title: Milestones
+---
+
+Here I provide a high level description of the functionality I am working towards. To set achievable goals, milestones will be rather small and the functionality I aim for may appear incomplete.
+
+Domain Terms are shown in **bold**. For a list of _DDD terms_, see <https://www.dddcommunity.org/resources/ddd_terms/>.
+
+
+## Current milestone (#1)
+
+Create the Fix command line application that provides basic functionality for **issues**. As storage use a single JSON file, located in a `.fix` subdirectory of the working directory.
+
+An **issue** is an _aggregate_ with the follwing _values_:
+
+- The **title** is a string of restricted length (6-120 characters) and character set (alphanumeric, space, punctuation without backspace and backtick)
+- The **description** is a unicode string, length theoretically unlimited (limited by storage format and other technical boundaries)
+- The **issue ID** is a string that is set when the issue is created and can never be changed. To avoid conflicts when Fix is used with Git (see [here]({% link _pages/about.md %})), consecutive numbers can not be used. Instead, an issue ID has a special format `aaa-bbb-ccc-ddd-xxxxxxx`: four blocks of 2-3 alphanumeric characters each, and a block of 7 hexadecimal characters. Blocks are separated by hyphens.
+- The **status** for now can have two possible values: `open` and `closed`
+
+For this first milestone, I want to be able to do the following:
+
+- **create** an **issue**: This _command_ creates a new **issue** and stores it in the **issue _repository_**. The **title** and **description** are parameters of the _command_, the **status** is `open`. The **issue ID** is generated by abbreviating the first four words of the title (if there are as many) and a hash of the title and description.
+- **set** the **status**: This _command_ changes the status of an **issue** to one of the two allowed values (see above).
+- **list** all existing **issues**: This _query_ shows a list (no specific order) of all **issues** with their **issue ID**, **titles**, and **status**. Titles may be abbreviated to fit on a single line.
+- **show** a single **issue**: This _query_ shows the **title**, **status**, and **description** of the **issue** with the given **issue ID**
+
+
+### Out of scope:
+- deletion of issues is not that important for now
+- editing of description and title should come soon, but not now
+- explicitly setting the issue ID (or part of it) may be a desirable feature for some future milestone
+- more fields for issues, like tags, comments, etc.
+- more allowed values for status