Skip to content
This repository was archived by the owner on Apr 27, 2026. It is now read-only.

docs(streaming_file): improve component description#4

Merged
aronchick merged 1 commit intomainfrom
docs/improve-description
Dec 17, 2025
Merged

docs(streaming_file): improve component description#4
aronchick merged 1 commit intomainfrom
docs/improve-description

Conversation

@aronchick
Copy link
Copy Markdown
Owner

@aronchick aronchick commented Dec 17, 2025

Summary

Comprehensive documentation improvements addressing reviewer feedback on PR warpstreamlabs#514.

Changes

Core Features Documentation

  • Clearly documents the minimum feature set: log rotation and truncation handling
  • Explains how rotation detection works (via inode changes)

Position Tracking Trade-off

  • Explicitly addresses the tension with Bento's "no disk persisted state" philosophy
  • Notes that state_dir is optional and can use tmpfs if crash recovery isn't needed

Platform Limitations

  • Documents fsnotify constraints (NFS/network filesystems don't work reliably)
  • Lists supported platforms (Linux, macOS, Windows, BSD)
  • Notes container environment considerations

Delivery Semantics

  • Clarifies exactly-once vs at-least-once behavior in different scenarios

Also includes:

  • Changed status to experimental (default) by removing Stable()
  • Simplified summary text

Address reviewer feedback by documenting:

- Core features: log rotation and truncation handling
- Position tracking trade-off vs Bento's "no disk state" philosophy
- Platform limitations (NFS, fsnotify constraints)
- Delivery semantics clarification

Also removed Stable() to use default experimental status and
simplified the summary.
@aronchick aronchick force-pushed the docs/improve-description branch from e8409a3 to 65a0190 Compare December 17, 2025 21:23
@aronchick aronchick marked this pull request as ready for review December 17, 2025 22:18
@aronchick aronchick merged commit 35ac32f into main Dec 17, 2025
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant