diff options
Diffstat (limited to 'doc.go')
| -rw-r--r-- | doc.go | 71 |
1 files changed, 71 insertions, 0 deletions
@@ -0,0 +1,71 @@ +// Package furgit provides low-level Git operations. +// +// Furgit provides absolutely no guarantees on correctness, performance, +// API stability. In particular, before version 1.0.0, no attempt at +// API stability is made at all, and breaking changes may be introduced +// in patch-level releases. See also the warranty and liability disclaimers +// in the license. +// +// Git libraries often center on a repository type that owns objects, refs, +// worktree state, and configuration behind a single facade. Furgit inverts +// that: objects are plain values, stored objects are separate types that +// associate objects with their object IDs, object storage and ref storage +// are sets of narrow interfaces consisting only of things that are truly +// reasonable for all implementations to satisfy, and every higher-level +// operation, such as commit traversal, reachability analysis, and +// recursive peeling, is built over those interfaces. +// +// While the [codeberg.org/lindenii/furgit/repository] package is where +// most users should begin, it only exists as one convenient composition of +// those pieces for the standard on-disk repository layout. Nothing inside +// furgit should depend on it; extensions to furgit such as alterntaive +// object stores must not depend on it either. +// +// # Contract labels +// +// Many furgit APIs document concurrency, dependency ownership, value lifetime, +// and close behavior using short labels. +// These labels summarize the API contract, but they do not replace the full +// doc comment on a package, type, function, method, constant, or variable. +// +// When both a type and one of its methods specify labels, the method-level +// labels take precedence for that operation. +// +// Concurrency labels: +// +// - MT-Safe: safe for concurrent use. +// - MT-Unsafe: not safe for concurrent use without external synchronization. +// +// Dependency labels: +// +// - Deps-Owned: the receiver takes ownership of all supplied dependencies +// where ownership is a reasonable concept. +// - Deps-Borrowed: the value borrows supplied dependencies. Also Life-Parent +// in most cases, unless those dependencies are not retained past +// construction. +// - Deps-Mixed: some supplied dependencies are owned and others are borrowed. +// +// Lifetime labels: +// +// - Life-Independent: returned values remain valid independently of the +// parent or provider. +// - Life-Parent: returned values are only valid while the parent or provider +// remains valid. +// - Life-Call: returned values are only valid for the duration of the +// current call, callback, or hook invocation. +// +// Close labels: +// +// - Close-Caller: the caller must close the returned value. +// - Close-No: the caller must not close the returned value directly. +// - Close-Idem: repeated Close calls are safe. +// +// Mutation labels: +// +// - Mut-Never: returned values must not be mutated. +// +// Unless Close-Idem is specified, repeated Close calls are undefined behavior. +// +// Unless a doc comment explicitly states otherwise, these labels describe the +// API contract only. They do not imply any specific implementation strategy. +package furgit |