From c8a0a0c688c3d99579810190b870b0fe8548e5c5 Mon Sep 17 00:00:00 2001
From: ssube <seansube@gmail.com>
Date: Sun, 30 Jun 2019 20:06:40 -0500
Subject: [PATCH] docs: document workflow

---
 docs/workflow.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 docs/workflow.md

diff --git a/docs/workflow.md b/docs/workflow.md
new file mode 100644
index 0000000..f78f45f
--- /dev/null
+++ b/docs/workflow.md
@@ -0,0 +1,117 @@
+# Workflow
+
+This document covers the project workflow, commit and merge messages, and how to release.
+
+- [Workflow](#Workflow)
+  - [Labels](#Labels)
+    - [Scopes](#Scopes)
+    - [Status](#Status)
+      - [Terminal Status](#Terminal-Status)
+      - [Transitions](#Transitions)
+    - [Types](#Types)
+  - [Issues](#Issues)
+    - [Issue Labels](#Issue-Labels)
+
+## Labels
+
+Consistent labels, Scopes, and types are used in conventional commit messages, branch names, and issue labels, thus
+tying them all together.
+
+### Scopes
+
+- build
+  - `.gitlab-ci.yml`
+  - `Makefile`
+  - `*.mk`
+- config
+  - `src/config/*`
+- container
+  - `Dockerfile`
+- docs
+  - `docs/*`
+- examples
+  - `examples/*`
+- package
+  - `package.json`
+- parser
+  - `src/parser/*`
+- rules
+  - `rules/*`
+- scripts
+  - `scripts/*`
+- visitor
+  - `src/visitor/*`
+
+### Status
+
+- new
+  - unaddressed, potentially unread
+- confirmed
+  - `type/bug`: reproduced
+  - `type/feature`: plausible addition
+- planned
+  - initial scope defined
+  - ready to be implemented
+- progress
+  - branch exists with commits
+  - may have a `WIP:` merge request
+- blocked
+  - branch exists with commits
+  - waiting for some dependency, prerequisite, etc
+
+#### Terminal Status
+
+- fixed
+  - `type/bug`: fix has been implemented and tested
+  - `type/feature`: initial scope has been implemented and tested
+- declined
+  - `type/bug`: could not be reproduced or will not be fixed
+  - `type/feature`: will not be added
+
+Do not close the issue until the corresponding branches have been merged and released.
+
+#### Transitions
+
+- `new -> confirmed`
+  - `type/bug`: bug has been reproduced and verified
+  - `type/feature`: feature to be planned
+- `new -> declined`
+  - `type/bug`: bug cannot be reproduced, fix would break existing features, cannot reasonably be implemented, etc
+  - `type/feature`: feature does not fit vision, cannot reasonably be implemented, etc
+- `confirmed -> planned`
+  - `type/bug`: bug will be fixed
+  - `type/feature`: feature has been researched and initial scope defined
+- `confirmed -> declined`
+  - `type/bug`: bug will not be fixed
+  - `type/feature`: feature has been researched, but will not be implemented
+- `planned -> progress`
+  - begin writing code
+- `progress -> blocked`
+  - waiting for some prerequisite
+- `progress -> fixed`
+  - `type/bug`: fix has been implemented and tested
+  - `type/feature`: initial scope has been implemented, tested, and documented
+- `progress -> declined`
+  - branch will not be merged
+- `blocked -> declined`
+  - prerequisite cannot be met
+
+### Types
+
+- feat
+  - new features
+  - additions to existing features
+- fix
+  - bug fixes
+- lint
+  - style changes
+  - not strictly necessary but improve code quality
+- update
+  - dependency updates
+  - typically handled by Renovate
+
+## Issues
+
+### Issue Labels
+
+Every issue must at least one label from each group: `scope/*`, `status/*`, `type/*`.