docs: document workflow

2019-06-30 20:06:40 -05:00 · 2019-06-30 20:06:40 -05:00 · c8a0a0c688
parent c41d9d0da2
commit c8a0a0c688
1 changed files with 117 additions and 0 deletions
--- a/docs/workflow.md
+++ 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/*`.