tools/go-cuckoo
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Releases 4 Wiki Activity

docs(adr): adr template, design principles adr #26

Merged
mvhutz merged 20 commits from docs/contract-v2 into main 2026-07-05 01:27:01 +00:00
Conversation 0 Commits 20 Files Changed 2
+18 -18
1 changed files with 18 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 7b0f016833 - Show all commits
docs/adr/001_design_principles.md
+18 -18
View File
@@ -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.