-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from 51ngul4r1ty/temp/kevin/update-docs-2024-01-23
Documentation Updates - Data Model, Data Catalog, Continuing Story Estimates etc.
- Loading branch information
Showing
4 changed files
with
253 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,108 @@ | ||
| Overview | ||
| ======== | ||
|
|
||
| This "Data Catalog" is intended as a place to describe the entities and what they contain. | ||
| While the "Data Model" docs provide context for why the entities exist that relates more to | ||
| business requirements, this catalog is purely a technical description of what the entities | ||
| are and what the fields contain. | ||
|
|
||
| This isn't intended as an all-encompassing definition of the entities. It merely covers | ||
| details that cannot easily be determined by common sense. | ||
|
|
||
| Entities | ||
| ======== | ||
|
|
||
| Entity Overview | ||
| --------------- | ||
|
|
||
| 1. `appuser` | ||
| The users that have access to the app- passwords are hashed to prevent them | ||
| from being revealed to others. | ||
| 2. `backlogitem` | ||
| The basic backlog item details- whether it is a story or an issue all will be | ||
| in this table. A backlog item can be grouped in other backlogs, but that | ||
| grouping information is not stored here. Currently `sprintbacklogitem` and | ||
| `productbacklogitem` provide this grouping data, but others may be added. | ||
| 3. `backlogitempart` | ||
| Each `backlogitem` has at least one part but can be split into more as needed | ||
| by the users. | ||
| 4. `backlogitemtag` | ||
| Future use: `backlogitem` instances can be tagged with a user-defined tag | ||
| (50 characters long currently). | ||
| 5. `counter` | ||
| Internal IDs are GUIDs so they're not very user-friendly. To allow items to | ||
| be more easily identified by users the `counter` entity exists to track the | ||
| last used counter numbers (specific to a `project` and backlog item type). | ||
| The `counter` entity relies on `projectsettings` to determine the counter | ||
| value format (a separate prefix for issues and stories is configured per | ||
| project, usually `i-` and `s-`). | ||
| 6. `productbacklogitem` | ||
| This represents the product backlog and is essentially a linked list to allow | ||
| it to be easily sequenced without requiring much overhead (millions of rows | ||
| could in theory be stored in it would support easy paging through this list). | ||
| 7. `project` | ||
| Multiple projects can be stored in this collection and the user can switch | ||
| between projects easily using this list. | ||
| 8. `projectsettings` | ||
| As mentioned above this contains the configuration for a project. Currently | ||
| only the `counter` configuration is stored, but this will be expanded in | ||
| future. | ||
| 9. `sprint` | ||
| The list of sprints is stored in this collection- and references the `project` | ||
| entity. | ||
| 10. `sprintbacklogitem` | ||
| Each sprint has its own list of backlog items- the sprint does not actually | ||
| reference the backlog item itself, but rather a part of the backlog item. | ||
| 11. `usersettings` | ||
| A user's preferences - currently only the selected project and theme. This | ||
| will be expanded in future. | ||
|
|
||
| Fields for `backlogitem` | ||
| ------------------------ | ||
|
|
||
| * `externalId` - When a backlog item is also stored in an external system this | ||
| ID will be populated. If it is not populated the `friendlyId` field will | ||
| instead be shown to the user. For example, `gh-323`. | ||
| * `friendlyId` - Every backlogitem will have a "friendly" ID that is easy to a | ||
| human to reason about and discuss (for example, `i-123` for an issue or | ||
| `s-456` for a story). | ||
| * `acceptanceCriteria` - Markdown data that contains the acceptance criteria for | ||
| a story or the repo steps of an issue. This is an optional field that will be | ||
| populated with `null` if not provided. | ||
| * `rolePhrase` - For example, `As a devops engineer` or | ||
| `As a developer using VS Code`. | ||
| * `storyPhrase` - For example, `I can deploy to Heroku` or `I can login`. | ||
| * `reasonPhrase` - For example, | ||
| for an issue - `without seeing a "self signed certificate" error` | ||
| or for a story - `so that I can correct bad data` | ||
| * `estimate` - Best practice story points: 0.25, 0.50, 1.00, 2.00, 3.00, 5.00, | ||
| 8.00, 13.00, 20.00, etc. (Atoll is strict about the standard fibonaccish | ||
| number system used by Scrum). | ||
| * `type` - 'story' or 'issue' | ||
| * `projectId` - foreign key reference to the `project` entity that this backlog | ||
| item belongs to. | ||
| * `status` - The overall status of a backlog item. For an item that has | ||
| multiple parts the status of the final part will determine the overall status | ||
| of the backlog item. | ||
| - `null` (treated the same as "N" - see below) | ||
| - "N" (not started) | ||
| - "P" (in progress) | ||
| - "D" (done) | ||
| - "A" (accepted) | ||
| - "R" (released) | ||
| * `totalParts` | ||
| - Used mainly for display purposes, this should correlate with the number | ||
| of `backlogitempart` items that related to this `backlogitem`. | ||
|
|
||
| Fields for `backlogitempart` | ||
| ---------------------------- | ||
|
|
||
| * `externalId` - Similar to `backlogitem`, but this ID is constructed by the | ||
| system by appending `-{part number}` to the `externalId` from the matching | ||
| `backlogitem`. | ||
| * `backlogitemId` - Foreign key reference to the associated `backlogitem`. | ||
| * `partIndex` - The part number starting with `1` and increment by `1` for each | ||
| additional part (this number is required to be unique). | ||
| * `points` - Each part has an estimate but it cannot be more than the original | ||
| backlog item's estimate. | ||
| * `status` - Same as `backlogitem`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| Overview | ||
| ======== | ||
|
|
||
| Continuing stories (through a concept known as "backlog item parts") will | ||
| most likely result in changing estimates. The system doesn't allow an estimate | ||
| to be increased in this scenario- the estimate can be the same or lower. The | ||
| reason for this comes down to calculating an accurate velocity. | ||
|
|
||
| Essentially, it should be possible to use velocity to forecast delivery | ||
| timelines. The idea is that the team estimates each item in the product | ||
| backlog, then it gets sorted in priority order and then a delivery estimate can | ||
| be determined based on the team velocity and the story point total. | ||
|
|
||
| Story points and velocity are team specific. If the team estimates a story and | ||
| then discovers that it will take longer than estimated, their velocity should go | ||
| down as they fail to deliver that story in the forecasted time. This will be | ||
| demonstrated in an example below. | ||
|
|
||
| Contuing Stories and Estimates (Example) | ||
| ---------------------------------------- | ||
|
|
||
| There are a couple of things that come into play here: | ||
| 1. Estimates equate to business value added and as such they are a measure of | ||
| forward progress towards delivering overall milestones. | ||
| 2. Estimates should be a reliable measure of how close the team is to reaching | ||
| that milestone. | ||
|
|
||
| As an example, let's say we have a team that has delivered the following | ||
| results: | ||
| * Sprint 1 - 25 points. | ||
| * Sprint 2 - 18 points. | ||
| * Sprint 3 - 23 points. After 3 sprints we compute velocity as 22 points. | ||
| * Sprint 4 | ||
| - they plan 22 points into the sprint and this includes an 8 pointer | ||
| that we will refer to as "Story A". | ||
| - they do the work and at the end of sprint 4, "Story A" is started but | ||
| incomplete. | ||
| - the developer working on the story reviews with the team and determines | ||
| that 3 story points have been achieved and there are 5 remaining points | ||
| (fibonaccish numbers should be used so the only options are: 0 + 8, 5 + 3, | ||
| or 3 + 5). | ||
| - we are not able to count the story as representing anything towards velocity | ||
| so the team's velocity becomes 18 + 23 + 14 => 18 1/3. | ||
| * Sprint 5 | ||
| - they plan 18 points into the sprint which includes the 5 remaining points. | ||
| - at the end of this sprint the work is completed and the team receives the | ||
| 8 points added to their velocity (essentially 18 + 3 = 21 points). | ||
| - now the team's velocity is 23 + 18 + 21 => 20 2/3. | ||
| * Sprint 6 | ||
| - they're now able to plan 20 points into this sprint. | ||
|
|
||
| Now, imagine they could re-estimate "Story A" as 13 points: | ||
| * Sprint 4 | ||
| - they plan 22 points into the sprint and this includes an 8 pointer | ||
| that we will refer to as "Story A". | ||
| - they do the work and at the end of sprint 4, "Story A" is started but | ||
| incomplete. | ||
| - the developer working on the story reviews with the team and determines | ||
| that this was a bigger story than anticipated so they decide it should've | ||
| been a 13 pointer. | ||
| - this has a number of negative consequences: | ||
| - estimates are no longer a commitment to deliver within a measurable | ||
| timeframe | ||
| - we've essentially gone backwards, because if we use a similar tecnnique as | ||
| above, we'd allow the team to pick 0 + 13, 5 + 8, or 8 + 5. They'd pick | ||
| the 5 + 8 to represent it with a similar ratio. | ||
| - we are not able to count the story as representing anything towards velocity | ||
| so the team's velocity becomes 18 + 23 + 14 => 18 1/3. | ||
| * Sprint 5 | ||
| - they plan 18 points into the sprint which includes the 8 remaining points. | ||
| - this time 10 points come from new stories vs 13 points last time | ||
| - the team gets more of a buffer, but since they didn't complete the 8 | ||
| pointer in the allotted 8 points they already have one at the expense of | ||
| overall decreased velocity, is this some kind of double accounting?! | ||
| - at the end of this sprint the work is completed and the team receives the | ||
| 13 points added to their velocity (essentially 18 + 5 = 23 points). | ||
| - however, let's assume they're not lazy, so they essentially had a forced | ||
| underplan by 3 pts and they pull in and complete a 3 pointer. | ||
| - so they've completed exactly the same stories, albeit with one that has | ||
| an inflated estimate. | ||
| - now the team's velocity is 23 + 18 + 23 (+3) => 22 1/3. | ||
| - somehow they failed to deliver a story when they said they would be now | ||
| they're back at the same velocity?! | ||
| * Sprint 6 | ||
| - they're now able to plan 22 points into this sprint. | ||
|
|
||
| Let's compare and contrast these 2 scenarios: | ||
|
|
||
| | | Disallowing Increased Estimate | Allowing Increased Estimate | | ||
| |-----------------|--------------------------------|------------------------------| | ||
| | Final Velocity | 20 | 22 | | ||
| | Starting Points | 101 | 101 | | ||
| | Achieved Points | 101 | 106 | | ||
| | Inflation | 0 | +5 | | ||
| | S5 impact | 21 -> 18 (reduced velocity) | 21 -> 18 (reduced velocity) | | ||
| | S5 new work | 13 (carry over was 5) | 10 (carry over was 8) | | ||
| | Effect | only 1 story affected in S5 | 2 stories affected in S5 | | ||
|
|
||
| If we allow the increased estimate developers may actually be more cautious and | ||
| that may result in decreased productivity. Pulling a 3 pointer in at the end of | ||
| the sprint may seem risky (because they may not finish it up). That effectively | ||
| decreases capacity by 3 points as a consequence. | ||
|
|
||
| It should be obvious from the table and this note above that it will have a | ||
| number of negative effects by allowing the increase of an estimate. |