@cratis/pi 7.103.3 → 7.103.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -24,7 +24,9 @@ exact commands.
|
|
|
24
24
|
|
|
25
25
|
- Read the `go` directive, build constraints and CI before choosing a feature.
|
|
26
26
|
The minimum is not the newest locally installed compiler; a `toolchain`
|
|
27
|
-
preference does not replace minimum-version testing. Do not raise it incidentally
|
|
27
|
+
preference does not replace minimum-version testing. Do not raise it incidentally
|
|
28
|
+
or rewrite unrelated code to modernize syntax. Verify unfamiliar APIs against the
|
|
29
|
+
documentation for that minimum, and keep experimental features opt-in.
|
|
28
30
|
- Iterators require Go 1.23; `T.Context` and `B.Loop` require 1.24;
|
|
29
31
|
stable `testing/synctest` and `WaitGroup.Go` require 1.25.
|
|
30
32
|
- Prefer the standard library when it meets the contract. Review dependency
|
|
@@ -33,6 +35,10 @@ exact commands.
|
|
|
33
35
|
including indirect minimum-version changes; keep sums consistent. A consumer
|
|
34
36
|
must not need a developer's workspace or local replacement.
|
|
35
37
|
- Never edit generated code; change its authoritative inputs and pinned generator.
|
|
38
|
+
- Start with a small public package surface aligned with caller workflows; put
|
|
39
|
+
implementation-only packages in `internal/` and keep optional adapters apart from
|
|
40
|
+
core behavior. Do not mandate `pkg/`. Avoid package initialization that performs
|
|
41
|
+
I/O, starts goroutines or mutates globals.
|
|
36
42
|
|
|
37
43
|
## Names, public APIs and values
|
|
38
44
|
|
|
@@ -44,11 +50,23 @@ exact commands.
|
|
|
44
50
|
- Document exported declarations with comments beginning with their names.
|
|
45
51
|
Explain nil/zero semantics, concurrency, ownership, cancellation, error identities
|
|
46
52
|
and cleanup. Add executable examples for important public workflows.
|
|
47
|
-
-
|
|
48
|
-
|
|
53
|
+
- Design exported APIs from realistic caller examples first and export only what
|
|
54
|
+
the library will support. Make zero values useful where possible; reject invalid
|
|
55
|
+
construction early. Use plain parameters or config structs for simple
|
|
56
|
+
configuration and functional options when extensibility outweighs the added
|
|
57
|
+
namespace; document option defaults, validation, ordering and duplicates.
|
|
58
|
+
- Reuse standard interfaces such as `io.Reader` and `http.Handler`; prefer concrete
|
|
59
|
+
returns unless an abstraction is part of the API. Use pointer receivers for
|
|
60
|
+
mutation or values that must not be copied, and avoid public embedding that
|
|
61
|
+
promotes dependency methods. Mark retired API with a `Deprecated:` paragraph
|
|
62
|
+
naming the replacement.
|
|
49
63
|
- Use named domain values instead of interchangeable primitives. Defined types
|
|
50
64
|
do not inherit codec methods; explicitly forward text/JSON codecs and test wire
|
|
51
65
|
formats. See `cratis-fundamentals-concept-go` when using Fundamentals.Go.
|
|
66
|
+
- Specify `Close` ownership, repeated-close behavior and use after close, and
|
|
67
|
+
document concurrent-use guarantees for clients, handles and callbacks.
|
|
68
|
+
- Use generics for meaningful type-safe reuse, not speculative abstraction; do not
|
|
69
|
+
replace domain types with `any` for plumbing convenience.
|
|
52
70
|
- Document whether slices, maps, config and results are owned, copied or borrowed.
|
|
53
71
|
Copying a slice/map header is not a detached copy. Do not copy a used mutex,
|
|
54
72
|
wait group or atomic value, or expose pooled bytes after returning their buffer.
|
|
@@ -62,7 +80,9 @@ exact commands.
|
|
|
62
80
|
return an `error` interface containing a typed nil.
|
|
63
81
|
- Add useful operation context. Handle/log an error at one boundary rather than
|
|
64
82
|
repeatedly logging and returning it. A partial or ambiguous write is not success
|
|
65
|
-
and must not trigger a blind retry.
|
|
83
|
+
and must not trigger a blind retry. Use sentinels for stable categories and typed
|
|
84
|
+
errors for structured details; translate dependency errors whose identity must
|
|
85
|
+
stay internal, and explain intentional suppression.
|
|
66
86
|
- Put `context.Context` first for blocking/cancelable work and propagate it through
|
|
67
87
|
RPCs, HTTP, storage and callbacks. Never escape caller cancellation by replacing
|
|
68
88
|
it with `Background`. Do not retain request contexts in long-lived clients.
|
|
@@ -73,6 +93,9 @@ exact commands.
|
|
|
73
93
|
|
|
74
94
|
## Goroutines, streams and iterators
|
|
75
95
|
|
|
96
|
+
- Prefer synchronous APIs and let callers place concurrency. A saturated
|
|
97
|
+
`errgroup.SetLimit` can block `Go`; use `errgroup` only when its cancellation
|
|
98
|
+
and error behavior fits.
|
|
76
99
|
- Each goroutine needs an owner, termination condition and observable join path.
|
|
77
100
|
Cancellation requests termination; it does not join workers.
|
|
78
101
|
- Bound workers, queues, subscriptions, buffers and retries; define backpressure.
|
|
@@ -85,6 +108,8 @@ exact commands.
|
|
|
85
108
|
- Preserve protocol metadata, tenancy, checkpoints and duplicate-delivery semantics.
|
|
86
109
|
No generic retry or stream helper may promise exactly-once effects.
|
|
87
110
|
- Validate remote TLS identities. Development exceptions must be explicit.
|
|
111
|
+
Bound untrusted payload sizes, fan-out and retained subscription state, and keep
|
|
112
|
+
long-lived subscription lifetimes apart from unary-call deadlines.
|
|
88
113
|
Use cryptographic randomness for secrets, never `math/rand`.
|
|
89
114
|
|
|
90
115
|
## Specifications and checks
|
|
@@ -98,10 +123,23 @@ exact commands.
|
|
|
98
123
|
- Cover error identity, nil/zero input, cancellation/deadlines, partial outcomes,
|
|
99
124
|
early stream exit and resource ownership. Bound fuzz duration and preserve
|
|
100
125
|
failing seeds. Use race checks where supported; race-free does not mean leak-free.
|
|
126
|
+
- Add a regression test for each corrected behavior, including error and boundary
|
|
127
|
+
cases. Use `httptest` or `bufconn` plus real-transport tests where needed, and
|
|
128
|
+
protobuf-aware comparison for generated types.
|
|
129
|
+
- Profile or benchmark a demonstrated problem before optimizing; add no pools,
|
|
130
|
+
caches or `unsafe` without measured justification.
|
|
101
131
|
- Run the repository's build, tests, formatting, vet and pinned golangci-lint gates,
|
|
102
132
|
with race and vulnerability scanning as separate checks. Respect the declared
|
|
103
133
|
minimum without silent toolchain upgrades. Report absent tools honestly.
|
|
104
134
|
|
|
135
|
+
## Compatibility and releases
|
|
136
|
+
|
|
137
|
+
- Prefer additive change: exported signature changes break callers, and adding a
|
|
138
|
+
method to an exported interface breaks its external implementations. Check struct comparability, embedding, defaults, errors and wire shape;
|
|
139
|
+
API-diff tools aid but cannot prove behavioral compatibility.
|
|
140
|
+
- Introduce `/v2` only with a migration and parallel-support plan. Never move a
|
|
141
|
+
published tag; issue a corrective release and retract when needed.
|
|
142
|
+
|
|
105
143
|
## Adaptation and attribution
|
|
106
144
|
|
|
107
145
|
This condensed rule adapts the repository-owned Go baseline at
|
|
@@ -23,7 +23,9 @@ exact commands.
|
|
|
23
23
|
|
|
24
24
|
- Read the `go` directive, build constraints and CI before choosing a feature.
|
|
25
25
|
The minimum is not the newest locally installed compiler; a `toolchain`
|
|
26
|
-
preference does not replace minimum-version testing. Do not raise it incidentally
|
|
26
|
+
preference does not replace minimum-version testing. Do not raise it incidentally
|
|
27
|
+
or rewrite unrelated code to modernize syntax. Verify unfamiliar APIs against the
|
|
28
|
+
documentation for that minimum, and keep experimental features opt-in.
|
|
27
29
|
- Iterators require Go 1.23; `T.Context` and `B.Loop` require 1.24;
|
|
28
30
|
stable `testing/synctest` and `WaitGroup.Go` require 1.25.
|
|
29
31
|
- Prefer the standard library when it meets the contract. Review dependency
|
|
@@ -32,6 +34,10 @@ exact commands.
|
|
|
32
34
|
including indirect minimum-version changes; keep sums consistent. A consumer
|
|
33
35
|
must not need a developer's workspace or local replacement.
|
|
34
36
|
- Never edit generated code; change its authoritative inputs and pinned generator.
|
|
37
|
+
- Start with a small public package surface aligned with caller workflows; put
|
|
38
|
+
implementation-only packages in `internal/` and keep optional adapters apart from
|
|
39
|
+
core behavior. Do not mandate `pkg/`. Avoid package initialization that performs
|
|
40
|
+
I/O, starts goroutines or mutates globals.
|
|
35
41
|
|
|
36
42
|
## Names, public APIs and values
|
|
37
43
|
|
|
@@ -43,11 +49,23 @@ exact commands.
|
|
|
43
49
|
- Document exported declarations with comments beginning with their names.
|
|
44
50
|
Explain nil/zero semantics, concurrency, ownership, cancellation, error identities
|
|
45
51
|
and cleanup. Add executable examples for important public workflows.
|
|
46
|
-
-
|
|
47
|
-
|
|
52
|
+
- Design exported APIs from realistic caller examples first and export only what
|
|
53
|
+
the library will support. Make zero values useful where possible; reject invalid
|
|
54
|
+
construction early. Use plain parameters or config structs for simple
|
|
55
|
+
configuration and functional options when extensibility outweighs the added
|
|
56
|
+
namespace; document option defaults, validation, ordering and duplicates.
|
|
57
|
+
- Reuse standard interfaces such as `io.Reader` and `http.Handler`; prefer concrete
|
|
58
|
+
returns unless an abstraction is part of the API. Use pointer receivers for
|
|
59
|
+
mutation or values that must not be copied, and avoid public embedding that
|
|
60
|
+
promotes dependency methods. Mark retired API with a `Deprecated:` paragraph
|
|
61
|
+
naming the replacement.
|
|
48
62
|
- Use named domain values instead of interchangeable primitives. Defined types
|
|
49
63
|
do not inherit codec methods; explicitly forward text/JSON codecs and test wire
|
|
50
64
|
formats. See `cratis-fundamentals-concept-go` when using Fundamentals.Go.
|
|
65
|
+
- Specify `Close` ownership, repeated-close behavior and use after close, and
|
|
66
|
+
document concurrent-use guarantees for clients, handles and callbacks.
|
|
67
|
+
- Use generics for meaningful type-safe reuse, not speculative abstraction; do not
|
|
68
|
+
replace domain types with `any` for plumbing convenience.
|
|
51
69
|
- Document whether slices, maps, config and results are owned, copied or borrowed.
|
|
52
70
|
Copying a slice/map header is not a detached copy. Do not copy a used mutex,
|
|
53
71
|
wait group or atomic value, or expose pooled bytes after returning their buffer.
|
|
@@ -61,7 +79,9 @@ exact commands.
|
|
|
61
79
|
return an `error` interface containing a typed nil.
|
|
62
80
|
- Add useful operation context. Handle/log an error at one boundary rather than
|
|
63
81
|
repeatedly logging and returning it. A partial or ambiguous write is not success
|
|
64
|
-
and must not trigger a blind retry.
|
|
82
|
+
and must not trigger a blind retry. Use sentinels for stable categories and typed
|
|
83
|
+
errors for structured details; translate dependency errors whose identity must
|
|
84
|
+
stay internal, and explain intentional suppression.
|
|
65
85
|
- Put `context.Context` first for blocking/cancelable work and propagate it through
|
|
66
86
|
RPCs, HTTP, storage and callbacks. Never escape caller cancellation by replacing
|
|
67
87
|
it with `Background`. Do not retain request contexts in long-lived clients.
|
|
@@ -72,6 +92,9 @@ exact commands.
|
|
|
72
92
|
|
|
73
93
|
## Goroutines, streams and iterators
|
|
74
94
|
|
|
95
|
+
- Prefer synchronous APIs and let callers place concurrency. A saturated
|
|
96
|
+
`errgroup.SetLimit` can block `Go`; use `errgroup` only when its cancellation
|
|
97
|
+
and error behavior fits.
|
|
75
98
|
- Each goroutine needs an owner, termination condition and observable join path.
|
|
76
99
|
Cancellation requests termination; it does not join workers.
|
|
77
100
|
- Bound workers, queues, subscriptions, buffers and retries; define backpressure.
|
|
@@ -84,6 +107,8 @@ exact commands.
|
|
|
84
107
|
- Preserve protocol metadata, tenancy, checkpoints and duplicate-delivery semantics.
|
|
85
108
|
No generic retry or stream helper may promise exactly-once effects.
|
|
86
109
|
- Validate remote TLS identities. Development exceptions must be explicit.
|
|
110
|
+
Bound untrusted payload sizes, fan-out and retained subscription state, and keep
|
|
111
|
+
long-lived subscription lifetimes apart from unary-call deadlines.
|
|
87
112
|
Use cryptographic randomness for secrets, never `math/rand`.
|
|
88
113
|
|
|
89
114
|
## Specifications and checks
|
|
@@ -97,10 +122,23 @@ exact commands.
|
|
|
97
122
|
- Cover error identity, nil/zero input, cancellation/deadlines, partial outcomes,
|
|
98
123
|
early stream exit and resource ownership. Bound fuzz duration and preserve
|
|
99
124
|
failing seeds. Use race checks where supported; race-free does not mean leak-free.
|
|
125
|
+
- Add a regression test for each corrected behavior, including error and boundary
|
|
126
|
+
cases. Use `httptest` or `bufconn` plus real-transport tests where needed, and
|
|
127
|
+
protobuf-aware comparison for generated types.
|
|
128
|
+
- Profile or benchmark a demonstrated problem before optimizing; add no pools,
|
|
129
|
+
caches or `unsafe` without measured justification.
|
|
100
130
|
- Run the repository's build, tests, formatting, vet and pinned golangci-lint gates,
|
|
101
131
|
with race and vulnerability scanning as separate checks. Respect the declared
|
|
102
132
|
minimum without silent toolchain upgrades. Report absent tools honestly.
|
|
103
133
|
|
|
134
|
+
## Compatibility and releases
|
|
135
|
+
|
|
136
|
+
- Prefer additive change: exported signature changes break callers, and adding a
|
|
137
|
+
method to an exported interface breaks its external implementations. Check struct comparability, embedding, defaults, errors and wire shape;
|
|
138
|
+
API-diff tools aid but cannot prove behavioral compatibility.
|
|
139
|
+
- Introduce `/v2` only with a migration and parallel-support plan. Never move a
|
|
140
|
+
published tag; issue a corrective release and retract when needed.
|
|
141
|
+
|
|
104
142
|
## Adaptation and attribution
|
|
105
143
|
|
|
106
144
|
This condensed rule adapts the repository-owned Go baseline at
|