Improve README: route users properly, improve keywords - #850
Merged
Conversation
Contributor
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe README now describes broader data support, repository scale, available interfaces, hosting options, and Git LFS behavior. ChangesREADME documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes 🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 44: Update the README sentence around the Oxen hosting options to replace
“self host” with the hyphenated “self-host,” preserving the surrounding wording
and links.
- Line 291: Update the introductory Git LFS and DVC performance wording in the
README to avoid broad claims unsupported by the available evidence. Limit the
statement to the benchmarked CelebA workflow, or name/link the relevant
Performance.md benchmark so the claim is explicitly scoped.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: c507cf78-9318-4e38-b2d6-cff5ed3e5437
📒 Files selected for processing (1)
README.md
CleanCut
enabled auto-merge
August 10, 2026 17:58
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 291: Update the sentence beginning “If you have ever tried Git LFS” in
the README introduction by replacing “became frustrated” with “have become
frustrated,” keeping the surrounding wording unchanged.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: aa68acf4-0bd7-4a87-b7a6-bd423f21a4ef
📒 Files selected for processing (1)
README.md
| Oxen was built by a team of machine learning engineers, who have spent countless hours in their careers managing datasets. We have used many different tools, but none of them were as easy to use and as ergonomic as we would like. | ||
|
|
||
| If you have ever tried [git lfs](https://git-lfs.com/) to version large datasets and became frustrated, we feel your pain. Solutions like git-lfs are too slow when it comes to the scale of data we need for machine learning. | ||
| If you have ever tried Git LFS to version large datasets and became frustrated, we feel your pain. Solutions like Git LFS are unwieldy and painfully slow in practice. We needed a faster alternative designed for large datasets. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Keep the verb tense consistent.
Change became to have become because the sentence begins with the present-perfect construction If you have ever tried.
Proposed wording
-If you have ever tried Git LFS to version large datasets and became frustrated, we feel your pain.
+If you have ever tried Git LFS to version large datasets and have become frustrated, we feel your pain.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| If you have ever tried Git LFS to version large datasets and became frustrated, we feel your pain. Solutions like Git LFS are unwieldy and painfully slow in practice. We needed a faster alternative designed for large datasets. | |
| If you have ever tried Git LFS to version large datasets and have become frustrated, we feel your pain. Solutions like Git LFS are unwieldy and painfully slow in practice. We needed a faster alternative designed for large datasets. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 291, Update the sentence beginning “If you have ever tried
Git LFS” in the README introduction by replacing “became frustrated” with “have
become frustrated,” keeping the surrounding wording unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The README is pretty important beyond informing people who stumble across our repo.
In particular, we want it to route people towards our website, both for storing their repos and the other features like fine tuning and inference, which we barely did at all before. We also had some keywords missing: "alternative" (think searching "git lfs alternative"), "training", "AI", "ML", "DVC". Also we were linking directly to git LFS for no good reason.
On the intro
I added examples to the "any data type" sentence (machine learning training data, model weights, game assets, studio media) which both adds concrete use cases to the intro and lets people understand why Oxen might be useful to them. Machine learning previously didn't appear until line 291. I also simplified the grammar in the git comparison sentence.
Components of oxen
The line about the different things we distribute was not very clear, not effective at routing people where they need to go, and contained filler. Most users should get pointed to the hub (oxen.ai), and everyone else should immediately see the self host path or the actual tool they need.
I made it route people to our actual website for the place they most likely want to store their repositories, provided explicitly as an alternative to self hosting on your own storage. I also reframed the CLI, Python package, and HTTP API as ways to interact with the remote and made it actually explain what the liboxen crate is for.
Why build Oxen
I tweaked the wording to match terms that people actually search for and mentioned "alternative to" and DVC. Comparison sites and a GitHub topic exist purely to farm "git lfs alternative", and similarly a lot of the comparison articles are to DVC. I also took that opportunity to use the AI and ML keywords.
I removed the link to the git lfs website because (a) it sends a frustrated Git LFS user straight back to Git LFS and (b) it makes no sense for us to give a direct link to our competitor's website.