familia 2.0.0.pre8 → 2.0.0.pre12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5ab18b134425a370c5d40f464e87747e85e713dc44c2a7906b7b024a66b23a4
-  data.tar.gz: f5a2e3fd2ca4553781b7f58f4f0e7a6d5e9228c18f34c7a1f5cf1af7695d580d
+  metadata.gz: 003a28f3135f0e89f6813e61cf08482350dbff865d2d97971998c714aafcc898
+  data.tar.gz: 6c713c9861043c71d7b2cfc99a37c4522e404ed7461d8dafed5462022735440b
 SHA512:
-  metadata.gz: fba2c7586cb19181461f90ef2718c767de34f034d51ebc23c1643c8b526cc9c28fe64a2c3e3e46857bc1d816c8e9db9f76a6b57510f9b918756558b5e09c6fc9
-  data.tar.gz: 2f98337dbe62a833b310e9ddcd5916a7971e2b551a0603dbb153fa3ba5c99a81e9dfe86270a0d0500b359625ea23efbebc58ab26b327a03fc5138ee643475472
+  metadata.gz: b0e4cb9f390ee0a3e1d83cc94a2248690fe757ce343665ef6e4ea6dbd2c74f8f7d07e352661380f0aac23e91f437315300a409847d28896b58b4ddf567d5e953
+  data.tar.gz: 2ec7616c6b2d64d522d441447ac93e58fe89f35eccd357bfdfc65305fc4324122148e5a3722c4bfd613d1f194fac1e5c0228d72b3774aa0e86e09bcdfe8b90fb

data/.github/workflows/ci.yml

@@ -66,3 +66,16 @@ jobs:
 
       - name: Run the tryouts
         run: bundle exec try -vf
+
+      - name: Validate examples
+        continue-on-error: true
+        run: |
+          echo "=== Validating example syntax ==="
+          find examples/ -name "*.rb" -exec ruby -c {} \;
+
+          echo "=== Running executable examples ==="
+          cd examples
+          for example in *.rb; do
+            echo "Running $example..."
+            ruby "$example" || echo "Warning: $example failed to run"
+          done

data/.github/workflows/docs.yml

@@ -41,7 +41,7 @@ jobs:
 
       - name: Build YARD documentation
         run: |
-          bundle exec yard doc --output-dir ./doc --readme README.md
+          bundle exec yard doc --output-dir ./doc
           # Ensure doc directory exists and create .nojekyll file to prevent GitHub Pages Jekyll processing
           mkdir -p ./doc
           touch ./doc/.nojekyll

data/.gitignore

@@ -12,20 +12,20 @@
 .*.json
 *.env
 *.log
-*.md
-.mcp.json
-!README.md
-!CLAUDE.md
 *.txt
-!LICENSE.txt
 .ruby-version
 appendonlydir
-etc/config
 log
 tmp
 vendor
 *.gem
 doc/
-!docs/overview.md
-!docs/connection_pooling.md
-!docs/wiki/**/*.md
+
+# Ignore WIP or temp dev files with uppercase names
+[A-Z]*.md
+
+# Exclusions
+!README.md
+!CHANGELOG.md
+!CLAUDE.md
+!LICENSE.txt

data/.rubocop.yml

@@ -34,6 +34,25 @@ AllCops:
     - "try/*.rb"
     - "vendor/**/*"
 
+#
+# Trailing commas
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+  Enabled: true
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+  Enabled: true
+
+Style/TrailingCommaInArguments:
+  Enabled: true
+
+Style/TrailingCommaInBlockArgs:
+  Enabled: true
+
+Lint/TrailingCommaInAttributeDeclaration:
+  Enabled: true
+
 Gemspec/DeprecatedAttributeAssignment:
   Enabled: true
 

data/.yardopts

@@ -4,6 +4,27 @@
 --markup-provider kramdown
 --protected
 --no-private
+--embed-mixin ClassMethods
+--embed-mixin Features
+--tag feature:"Feature"
+--tag since:"Since Version"
+--tag example:"Example Usage"
+--tag note:"Note"
+--tag warning:"Warning"
+--tag deprecated:"Deprecated"
+--hide-tag nodoc
+--exclude lib/familia/version.rb
 lib/**/*.rb
 -
-- LICENSE.txt
+CHANGELOG.md
+LICENSE.txt
+docs/guides/Home.md
+docs/guides/Getting-Started.md
+docs/guides/Feature-System-Guide.md
+docs/guides/Relationships-Guide.md
+docs/guides/relationships-methods.md
+docs/guides/Encrypted-Fields-Overview.md
+docs/guides/Connection-Pooling-Guide.md
+docs/reference/api-technical.md
+docs/migration/*.md
+examples/*.rb

data/CHANGELOG.md

@@ -0,0 +1,247 @@
+# CHANGELOG.md
+
+All notable changes to Familia are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!--scriv-insert-here-->
+
+<a id='changelog-2.0.0.pre12'></a>
+## 2.0.0.pre12 — 2025-09-04
+
+### Added
+
+- Added the `Familia::VerifiableIdentifier` module to create and verify identifiers with an embedded HMAC signature. This allows an application to stateless-ly confirm that an identifier was generated by itself, preventing forged IDs from malicious sources.
+
+- **Scoped VerifiableIdentifier**: Added `scope` parameter to `generate_verifiable_id()` and `verified_identifier?()` methods, enabling cryptographically isolated identifier namespaces for multi-tenant, multi-domain, or multi-environment applications while maintaining full backward compatibility with existing code.
+
+### Changed
+
+- ObjectIdentifier feature now tracks which generator (uuid_v7, uuid_v4, hex, or custom) was used for each objid to provide provenance information for security-sensitive operations.
+- Updated external identifier derivation to normalize objid format based on the known generator type, eliminating format ambiguity between UUID and hex formats.
+
+- Refactored identifier generation methods for clarity and consistency. Method `generate_objid` is now `generate_object_identifier`, and `generate_external_identifier` is now `derive_external_identifier` to reflect its deterministic nature.
+
+### Removed
+
+- Removed the `generate_extid` class method, which was less secure than the instance-level derivation logic.
+
+### Security
+
+- Hardened external identifier derivation with provenance validation. ExternalIdentifier now validates that objid values come from the ObjectIdentifier feature before deriving external identifiers, preventing derivation from potentially malicious or unvalidated objid values while maintaining deterministic behavior for legitimate use cases.
+
+- Improved the security of external identifiers (`extid`) by using the internal object identifier (`objid`) as a seed for a new random value, rather than deriving the `extid` directly. This prevents potential information leakage from the internal `objid`.
+
+### Documentation
+
+- Added detailed YARD documentation for `VerifiableIdentifier`, explaining how to securely generate and manage the required `VERIFIABLE_ID_HMAC_SECRET` key.
+
+### AI Assistance
+
+- Security analysis of external identifier derivation and hardened design approach was discussed and developed with AI assistance, including provenance tracking, validation logic, format normalization, and comprehensive test updates.
+
+- Implementation of scoped verifiable identifiers was developed with AI assistance to ensure cryptographic security properties and comprehensive test coverage.
+
+<a id='changelog-2.0.0.pre11'></a>
+## 2.0.0.pre11 - 2025-09-03
+
+### Added
+
+- **Enhanced Feature System**: Introduced a hierarchical feature system with ancestry chain traversal for model-specific feature registration. This enables better organization, standardized naming, and automatic loading of project-specific features via the new `Familia::Features::Autoloader` module.
+- **Improved SafeDump DSL**: Replaced the internal `@safe_dump_fields` implementation with a cleaner, more robust DSL using `safe_dump_field` and `safe_dump_fields` methods.
+- Added `generate_short_id` and `shorten_securely` utility methods for creating short, secure identifiers, adapted from `OT::Utils::SecureNumbers`.
+- For a detailed guide on migrating to the new feature system, see `docs/migration/v2.0.0-pre11.md`.
+
+### Changed
+
+- External identifier now raises an `ExternalIdentifierError` if the model does not have an objid field. Previously: returned nil. In practice this should never happen, since the external_identifier feature declares its dependency on object_identifier.
+- Moved lib/familia/encryption_request_cache.rb to lib/familia/encryption/request_cache.rb for consistency.
+- **Simplified ObjectIdentifier Feature Implementation**: Consolidated the ObjectIdentifier feature from two files (~190 lines) to a single file (~140 lines) by moving the ObjectIdentifierFieldType class inline. This reduces complexity while maintaining all existing functionality including lazy generation, data integrity preservation, and multiple generator strategies.
+- **Renamed Identifier Features to Singular Form**: Renamed `object_identifier` → `object_identifier` and `external_identifier` → `external_identifier` for more accurate naming. Added full-length aliases (`object_identifier`/`external_identifier`) alongside the short forms (`objid`/`extid`) for clarity when needed.
+- **Simplified ExternalIdentifier Feature Implementation**: Consolidated the ExternalIdentifier feature from two files (~240 lines) to a single file (~120 lines) by moving the ExternalIdentifierFieldType class inline, following the same pattern as ObjectIdentifier.
+
+### Fixed
+
+- Fixed external identifier generation returning all zeros for UUID-based objids. The `shorten_to_external_id` method now correctly handles both 256-bit secure identifiers and 128-bit UUIDs by detecting input length and applying appropriate bit truncation only when needed.
+
+### Security
+
+- Improved input validation in `shorten_to_external_id` method by replacing insecure character count checking with proper bit length calculation and explicit validation. Invalid inputs now raise clear error messages instead of being silently processed incorrectly.
+
+<a id='changelog-2.0.0-pre10'></a>
+## 2.0.0-pre10 - 2025-09-02
+
+### Added
+
+- The `Familia::Horreum` initializer now supports creating an object directly from its identifier by passing a single argument (e.g., `Customer.new(customer_id)`). This provides a more convenient and intuitive way to instantiate objects from lookups.
+
+- Automatic indexing and class-level tracking on `save()` operations, eliminating the need for manual index updates.
+- Enhanced collection syntax supports the Ruby-idiomatic `<<` operator for more natural relationship management.
+
+### Changed
+
+- The `member_of` relationship is now bidirectional. A single call to `member.add_to_owner_collection(owner)` is sufficient to establish the relationship, removing the need for a second, redundant call on the owner object. This fixes bugs where members could be added to collections twice.
+
+- **BREAKING**: Refactored Familia Relationships API to remove "global" terminology and simplify method generation. (Closes #86)
+- Split `generate_indexing_instance_methods` into focused `generate_direct_index_methods` and `generate_relationship_index_methods` for better separation between direct class-level and relationship-based indexing.
+- Simplified method generation by removing complex global vs parent conditionals.
+- All indexes are now stored at the class level for consistency.
+
+### Fixed
+
+- Fixed a bug in the `class_indexed_by` feature where finder methods (e.g., `find_by_email`) would fail to correctly instantiate objects from the index, returning partially-formed objects.
+
+- Refactored connection handling to properly cache and reuse Redis connections. This eliminates repetitive "Overriding existing connection" warnings and improves performance.
+
+- Method generation now works consistently for both `class_indexed_by` and `indexed_by` with a `parent:`.
+- Resolved metadata storage issues for dynamically created classes.
+- Improved error handling for nil class names in tracking relationships.
+
+### Documentation
+
+- Updated the `examples/relationships_basic.rb` script to reflect the improved, bidirectional `member_of` API and to ensure a clean database state for each run.
+
+### AI Assistance
+
+- This refactoring was implemented with Claude Code assistance, including comprehensive test updates and API modernization.
+
+<a id='changelog-2.0.0-pre9'></a>
+## 2.0.0-pre9 - 2025-09-02
+
+### Added
+
+- Added `class_tracked_in` method for global tracking relationships following Horreum's established `class_` prefix convention
+- Added `class_indexed_by` method for global index relationships with consistent API design
+
+### Changed
+
+- **BREAKING**: `tracked_in :global, collection` syntax now raises ArgumentError - use `class_tracked_in collection` instead
+- **BREAKING**: `indexed_by field, index, context: :global` syntax replaced with `class_indexed_by field, index`
+- **BREAKING**: `indexed_by field, index, context: SomeClass` syntax replaced with `indexed_by field, index, parent: SomeClass`
+- Relationships API now provides consistent parameter naming across all relationship types
+
+### Documentation
+
+- Updated Relationships Guide with new API syntax and migration examples
+- Updated relationships method documentation with new method signatures
+- Updated basic relationships example to demonstrate new API patterns
+- Added tryouts test coverage in try/features/relationships/relationships_api_changes_try.rb
+
+
+<a id='changelog-2.0.0-pre8'></a>
+## 2.0.0-pre8 - 2025-09-01
+
+### Added
+
+- Implemented Scriv-based changelog system for sustainable documentation
+- Added fragment-based workflow for tracking changes
+- Created structured changelog templates and configuration
+
+### Documentation
+
+- Set up Scriv configuration and directory structure
+- Created README for changelog fragment workflow
+
+<!-- scriv-end-here -->
+
+<a id='changelog-2.0.0-pre7'></a>
+## 2.0.0-pre7 - 2025-08-31
+
+### Added
+
+- Comprehensive relationships system with three relationship types:
+  - `tracked_in` - Multi-presence tracking with score encoding
+  - `indexed_by` - O(1) hash-based lookups
+  - `member_of` - Bidirectional membership with collision-free naming
+- Categorical permission system with bit-encoded permissions
+- Time-based permission scoring for temporal access control
+- Permission tier hierarchies with inheritance patterns
+- Scalable permission management for large object collections
+- Score-based sorting with custom scoring functions
+- Permission-aware queries filtering by access levels
+- Relationship validation framework ensuring data integrity
+
+### Changed
+
+- Performance optimizations for large-scale relationship operations
+
+### Security
+
+- GitHub Actions security hardening with matrix optimization
+
+
+<a id='changelog-2.0.0-pre6'></a>
+## 2.0.0-pre6 - 2025-08-15
+
+### Added
+
+- New `save_if_not_exists` method for conditional persistence
+- Atomic persistence operations with transaction support
+- Enhanced error handling for persistence failures
+- Improved data consistency guarantees
+
+### Changed
+
+- Connection provider pattern for flexible pooling strategies
+- Multi-database support with intelligent pool management
+- Thread-safe connection handling for concurrent applications
+- Configurable pool sizing and timeout management
+- Modular class structure with cleaner separation of concerns
+- Enhanced feature system with dependency management
+- Improved inheritance patterns for better code organization
+- Streamlined base class functionality
+
+### Fixed
+
+- Critical security fixes in Ruby workflow vulnerabilities
+- Systematic dependency resolution via multi-constraint optimization
+
+
+<a id='changelog-2.0.0-pre5'></a>
+## 2.0.0-pre5 - 2025-08-05
+
+### Added
+
+- Field-level encryption with transparent access patterns
+- Multiple encryption providers:
+  - XChaCha20-Poly1305 (preferred, requires rbnacl)
+  - AES-256-GCM (fallback, OpenSSL-based)
+- Field-specific key derivation for cryptographic domain separation
+- Configurable key versioning supporting key rotation
+- Non-persistent field storage for sensitive runtime data
+- RedactedString wrapper preventing accidental logging/serialization
+- Memory-safe handling of sensitive data in Ruby objects
+- API-safe serialization excluding transient fields
+
+### Security
+
+- Encryption field security hardening with additional validation
+- Enhanced memory protection for sensitive data handling
+- Improved key management patterns and best practices
+- Security test suite expansion with comprehensive coverage
+
+
+<a id='changelog-2.0.0-pre'></a>
+## 2.0.0-pre - 2025-07-25
+
+### Added
+
+- Complete API redesign for clarity and modern Ruby conventions
+- Valkey compatibility alongside traditional Redis support
+- Ruby 3.4+ modernization with fiber and thread safety improvements
+- Connection pooling foundation with provider pattern architecture
+
+### Changed
+
+- `Familia::Base` replaced by `Familia::Horreum` as the primary base class
+- Connection configuration moved from simple string to block-based setup
+- Feature activation changed from `include` to `feature` declarations
+- Method naming updated for consistency (`delete` → `destroy`, `exists` → `exists?`, `dump` → `serialize`)
+
+### Documentation
+
+- YARD documentation workflow with automated GitHub Pages deployment
+- Comprehensive migrating guide for v1.x to v2.0.0-pre transition
+
+<!-- scriv-end-here -->

data/CLAUDE.md

@@ -32,9 +32,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **Debugging options:**
 - **Stack traces**: `bundle exec try -s` (stack traces without debug logging)
+- **Verbose failures**: `bundle exec try -vfs` (detailed failure output)
 - **Debug mode**: `bundle exec try -D` (additional logging including stack traces)
-- **Verbose failures**: `bundle exec try -vf` (detailed failure output)
-- **Fresh context**: `bundle exec try --fresh-context` (isolate test cases)
+- **Shared context**: `bundle exec try --shared-context` (DEFAULT - reuse shared context across setup, testcases, and teardown)
+- **Fresh context**: `bundle exec try --no-shared-context` (isolate test cases, no shared variables)
 
 *Note: Use `--agent` mode for optimal token efficiency when analyzing test results programmatically.*
 
@@ -44,21 +45,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Generate documentation**: `bundle exec yard`
 - **Code linting**: `bundle exec rubocop`
 
+### Changelog Management
+
+Add changelog fragment with each user-facing or documented change (optional but encouraged). See:
+@changelog.d/README.md
+
 ### Known Issues & Quirks
-- **Reserved Keywords**: Cannot use `ttl`, `db`, `redis` as field names - use prefixed alternatives
+- **Reserved Keywords**: Cannot use `ttl`, `db`, `valkey`, `redis` as field names - use prefixed alternatives
 - **Empty Identifiers**: Cause stack overflow in key generation - validate before operations
 - **Connection Pool Race Conditions**: Thread safety issues under high concurrency
-- **Manual Key Sync**: `key` field doesn't auto-sync with identifier changes
-- **RedisType Redis Parameter**: `:redis` parameter silently ignored (missing setter)
 
 ### Debugging
-- **Database command logging**: `tail plop.log` - Real-time Database command monitoring
+- **Database command logging**: You can request real-time Database command monitoring from the user
   - Shows all Database operations with timestamps, database numbers, and full commands
   - Updates live as tests run or code executes
-  - Essential for debugging Familia ORM Database interactions
-
-### Testing Framework
-This project uses `tryouts` instead of RSpec/Minitest. Test files are located in the `try/` directory and follow the pattern `*_try.rb`.
+  - Essential for debugging Familia ORM Database interactions, multi/exec, pipelining, logical_database issues
 
 ## Architecture Overview
 
@@ -85,7 +86,7 @@ This project uses `tryouts` instead of RSpec/Minitest. Test files are located in
 Familia uses a modular feature system where features are mixed into classes:
 - **Expiration** (`lib/familia/features/expiration.rb`) - TTL management with cascading
 - **SafeDump** (`lib/familia/features/safe_dump.rb`) - API-safe object serialization
-- **Quantization** (`lib/familia/features/quantization.rb`) - Time-based data bucketing
+- **Relationships** (`lib/familia/features/relationships.rb`) - CRUD operations for related objects
 
 #### Key Architectural Patterns
 
@@ -107,15 +108,6 @@ end
 - Proc: `identifier ->(user) { "user:#{user.email}" }`
 - Array: `identifier [:type, :email]`
 
-### Directory Structure
-
-- `lib/familia.rb` - Main entry point and module definition
-- `lib/familia/horreum/` - Horreum class implementation (class_methods, commands, serialization, etc.)
-- `lib/familia/data_type/` - Valkey/Redis type implementations and commands
-- `lib/familia/features/` - Modular feature implementations
-- `try/` - Test files using tryouts framework
-- `try/test_helpers.rb` - Shared test utilities and sample classes
-
 ### Database Connection Management
 - Connection handling in `lib/familia/connection.rb`
 - Settings management in `lib/familia/settings.rb`
@@ -125,46 +117,7 @@ end
 ### Important Implementation Notes
 
 **Field Initialization**: Objects can be initialized with positional args (brittle) or keyword args (robust). Keyword args are recommended.
-
 **Serialization**: Uses JSON by default but supports custom `serialize_value`/`deserialize_value` methods.
-
 **Database Key Generation**: Automatic key generation using class name, identifier, and field/type names (aka dbkey). Pattern: `classname:identifier:fieldname`
-
 **Memory Efficiency**: Only non-nil values are stored in keystore database to optimize memory usage.
-
 **Thread Safety**: Data types are frozen after instantiation to ensure immutability.
-
-## Common Patterns
-
-### Defining a Horreum Class
-```ruby
-class Customer < Familia::Horreum
-  feature :safe_dump
-  feature :expiration
-
-  identifier_field :custid
-  default_expiration 5.years
-
-  field :custid
-  field :email
-  list :sessions
-  hashkey :settings
-end
-```
-
-### Using Features
-```ruby
-# Safe dump for API responses
-customer.safe_dump  # Returns only whitelisted fields
-
-# Expiration management
-customer.update_expiration(default_expiration: 1.hour)
-```
-
-### Transaction Support
-```ruby
-customer.transaction do |conn|
-  conn.set("key1", "value1")
-  conn.zadd("key2", score, member)
-end
-```

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre8)
+    familia (2.0.0.pre12)
       benchmark
       connection_pool
       csv

data/README.md

@@ -118,6 +118,56 @@ user.transaction do |conn|
 end
 ```
 
+### Object Relationships
+
+Familia includes a powerful relationships system for managing object associations:
+
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+
+  identifier_field :custid
+  field :custid, :name, :email
+  set :domains  # Collection for related objects
+
+  # Automatic indexing and tracking
+  class_indexed_by :email, :email_lookup
+  class_tracked_in :all_customers, score: :created_at
+end
+
+class Domain < Familia::Horreum
+  feature :relationships
+
+  identifier_field :domain_id
+  field :domain_id, :name, :status
+
+  # Bidirectional membership
+  member_of Customer, :domains
+end
+
+# Clean, Ruby-like syntax
+customer = Customer.new(custid: "cust123", email: "admin@acme.com")
+customer.save  # Automatically indexed and tracked
+
+domain = Domain.new(domain_id: "dom456", name: "acme.com")
+customer.domains << domain  # Clean collection syntax
+
+# Fast O(1) lookups
+found_customer = Customer.find_by_email("admin@acme.com")
+```
+
+## Advanced Features
+
+### Relationships and Associations
+
+Familia provides three types of relationships with automatic management:
+
+- **`member_of`** - Bidirectional membership with clean `<<` operator support
+- **`indexed_by`** - O(1) hash-based field lookups (class-level or relationship-scoped)
+- **`tracked_in`** - Scored collections for rankings, time-series, and analytics
+
+All relationships support automatic indexing and tracking - objects are automatically added to class-level collections when saved, with no manual management required.
+
 ## Organizing Complex Models
 
 For large applications, you can organize model complexity using custom features:
@@ -153,9 +203,19 @@ end
 
 This keeps complex models organized while maintaining Familia's clean, declarative style.
 
-## Conclusion
+## AI Development Assistance
+
+This version of Familia was developed with assistance from AI tools. The following tools provided significant help with architecture design, code generation, and documentation:
+
+- **Google Gemini** - Refactoring, code generation, and documentation.
+- **Claude Sonnet 4, Opus 4.1** - Architecture design, code generation, and documentation
+- **Claude Desktop & Claude Code (Max plan)** - Interactive development sessions and debugging
+- **GitHub Copilot** - Code completion and refactoring assistance
+- **Qodo Merge Pro** - Code review and quality improvements
+
+I remain responsible for all design decisions and the final code. I believe in being transparent about development tools, especially as AI becomes more integrated into our workflows as developers.
 
-Familia provides a powerful and flexible way to work with Valkey-compatible in Ruby applications. Its features like automatic expiration, safe dumping, and quantization make it suitable for a wide range of use cases, from simple key-value storage to complex time-series data management.
+## Epilogue
 
 For more information, visit:
 - [Github Repository](https://github.com/delano/familia)

data/changelog.d/README.md

@@ -0,0 +1,77 @@
+# Changelog Fragments
+
+This directory contains changelog fragments managed by [Scriv](https://scriv.readthedocs.io/).
+
+## Our Approach
+
+Changelogs are for humans and agents, not just machines. We follow the core principles of [Keep a Changelog](https://keepachangelog.com) and semvar to ensure our release notes are clear, consistent, and useful.
+
+To achieve this, we use a fragment-based workflow with `scriv`. Instead of a single, large `CHANGELOG.md` file that can cause merge conflicts, each developer includes a small changelog fragment with their pull request. At release time, these fragments are collected and aggregated into the main changelog.
+
+This approach provides several benefits:
+- **Reduces Merge Conflicts:** Developers can work in parallel without conflicting over a central changelog file.
+- **Improves Developer Experience:** Creating a small, focused fragment is a simple and repeatable task during development.
+- **Ensures Consistency:** Automation helps maintain a consistent structure for all changelog entries.
+- **AI Transparency:** An opportunity to be specific and detailed about the assistance provided.
+- **Builds Trust:** A clear and well-maintained changelog communicates respect for our users and collaborators.
+
+## Relevant paths
+
+* `changelog.d/` - (e.g. changelog.d/YYYYMMDD_HHmmss_username_branch.md)
+* `docs/migrating/` - (e.g. docs/migrating/v2.0.0-pre.md)
+* `CHANGELOG.md` - The full changelog for all releases, in reverse chronological order. Careful: LARGE DOCUMENT. Limit reading to the first 50 lines.
+
+* `setup.cfg` - Scriv tool settings
+
+## How to Add a Changelog Entry
+
+1.  **Create a New Fragment:**
+
+```bash
+# This will create a new file in the `changelog.d/` directory.
+scriv create
+```
+
+2.  **Edit the Fragment File:**
+Open the newly created file and add your entry under the relevant category. See the guidelines below for writing good CHANGELOG entries.
+
+3. **Add or Update Migrating Guide:** (optional)
+Include technical details to help developers update to the new version. Start with a specific introduction, e.g. "This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects.". Including code snippets and multi-line content that is too detailed for the CHANGELOG.
+
+Use the content of an existing `docs/migrating/vMajor.Minor.Patch*.md file as a reference.
+
+Compare the headers of your draft content with the headers of the previous migration guide to make sure it does not repeat or overlap.
+
+4.  **Commit with Your Code:**
+```bash
+git add changelog.d/YYYYMMDD_HHmmss_username_branch.md [docs/migrating/v2.0.0-pre.md]
+git commit
+```
+
+## Fragment Guidelines
+
+- **One Fragment Per Change:** Keep each fragment focused on a single feature, fix, or improvement.
+- **Documenting AI Assistance:** If a change involved significant AI assistance, place it in its own fragment. This ensures the `### AI Assistance` section clearly corresponds to the single change described in that fragment.
+- **Write for a Human Audience:** Describe the *impact* of the change, not just the implementation details.
+    - **Good:** "Improved the performance and stability of Redis connections under high load."
+    - **Bad:** "Refactored the `RedisManager`."
+- **Be Specific:** Avoid generic messages like "fixed a bug." Clearly state what was fixed.
+- **Include Context:** Reference issue or pull request numbers to provide a link to the discussion and implementation details. `scriv` will automatically create links for them.
+    - **Example:** `- Fixed a bug where users could not reset their passwords. PR #123`
+
+### Categories
+
+Use these categories:
+
+- **Added**: New features or capabilities.
+- **Changed**: Changes to existing functionality.
+- **Deprecated**: Soon-to-be removed features.
+- **Removed**: Now removed features.
+- **Fixed**: Bug fixes.
+- **Security**: Security-related improvements.
+- **Documentation**: Documentation improvements.
+- **AI Assistance**: Significant AI assistance in the change, including discussion, rubber ducking, formatting, writing documentation, writing tests.
+
+## Release Process
+
+At release time, scriv will collect all fragments into the main `CHANGELOG.md` file with th command `scriv collect`. The version is taken automatically from `lib/familia/version.rb`.

data/docs/archive/.gitignore

@@ -0,0 +1,2 @@
+# Even all uppercase markdown docs get the blues
+!*.md