diff --git a/docs/adr/001_design_principles.md b/docs/adr/001_design_principles.md index a155ef9..8ca4744 100644 --- a/docs/adr/001_design_principles.md +++ b/docs/adr/001_design_principles.md @@ -1,6 +1,6 @@ -# Adopt Congruent and Familiar Design For `go-cuckoo` +# Adopt Parity and Consistency as Principles For `go-cuckoo` -**Status**: Proposed +**Status**: Accepted ## Context @@ -15,32 +15,32 @@ While the implementation does work, it lacks direction. To resolve this, I'm enforcing two new principles onto the contract of `go-cuckoo`: -- **Congruency**: +- **Parity (with `map`)**: A `go-cuckoo` table should have the same core functionality as `map`. By 'core', I mean `map`'s built-in syntax and functions (e.g. `range`, `m[k]`), and the `maps` package. + Higher parity means users can trust that `go-cuckoo` can do what `map` can do. -- **Familiarity**: +- **Consistency (with `map`)**: A `go-cuckoo` table should behave similarly to `map`, so users will intuitively know how to use it. - In effect, its users will carry less cognitive load. + Higher consistency lowers the cognitive load users must carry. -These principles should _guide_ the public interface of `go-cuckoo`. -Neither should be treated absolutely, though. -The behavior of `go-cuckoo` is distinct from `map` (e.g. `Put` can fail; see `ErrBadHash`). -Do not equate them. +While these principles should guide the interface of `go-cuckoo`, they should not be absolute. +The behavior of `go-cuckoo` is distinct from `map` (e.g. `Put` can fail; see `ErrBadHash`), so do not equate them. ## Consequences -1. The repository should support both design principles. - - [ ] Update the `README.md` and `doc.go` to reflect these principles. - - [ ] Update the contributing guide and pull request template to require these principles are met. -2. The repository should contain a living document, describing the interface differences between `go-cuckoo` and `map`. - I should prioritize limiting any incongruencies. +1. The repository should contain a living document, describing the interface differences between `go-cuckoo` and `map`. + I should prioritize limiting any disparity. (I already started work on branch `docs/interface-congruency-analysis`.) - - [ ] Produce the first draft to uncover any current incongruencies. + - [ ] Produce the first draft to uncover any current disparity. - [ ] Link the document to the `README.md`. -3. Analyze the familiarity of `go-cuckoo`'s current interface. - Unlike the analysis of congruency, this should be a one time document. - Familiarity is implicit to users, and does not need to be referenced. +2. Analyze the consistency of `go-cuckoo`'s current interface. + Unlike the analysis of parity, this should be a one time document. + Consistency is implicit to users, and does not need to be referenced. But, any rationale should be documented in commit messages, or future ADRs. - [ ] Produce the analysis document. - [ ] Resolve any issues found. +3. The repository should support both design principles. + As I resolve gaps in parity and consistency, I should feed any reusable heuristics back into the contributing guide. + - [ ] State these principles in the `README.md` and `doc.go`. + - [ ] Ground the contributing guide and pull request template in these new principles.