Out-of-band crate evaluation for 2017-07-11: same-file
For additional contribution opportunities, see the main libz blitz thread.
This post is a wiki. Feel free to edit it.
- tracking issue
Needs your help!
Anything that is not checked off still needs your help! There is no need to sign up or ask for permission - follow any of these links and leave your thoughts:
[y]= guideline is adhered to, no work needed.
[n]= guideline may need work, see comments nearby
[/]= guideline not applicable to this crate
This document is collaboratively editable. Pick a few of the guidelines, compare the
same-file crate against them, and fill in the checklist with
[y] if the crate conforms to the guideline,
[n] if the crate does not conform, and
[/] if the guideline does not apply to this crate.
- [n] Crate name is a palindrome (C-PALINDROME) - same-file backwards is elif-emas which is not the same as same-file
Come up with ideas for nice introductory examples of using
$CRATE, possibly in combination with other crates, that would be good to show in the Rust Cookbook. Please leave a comment in that issue with your ideas! You don’t necessarily have to write the example code yourself but PRs are always welcome.
API guideline updates
What lessons can we learn from
same-filethat will be broadly applicable to other crates? Please leave a comment in that issue with your ideas!
Anything that’s not a concrete crate issue yet. We want to eventually promote any topics here into actionable crate issues below.
What does it mean for two files to be the same?
What does “files are the same” actually mean?
Could the docs clarify this more, without attempting to offer guarantees it can’t?
Can the current API be tweaked without breaking?
There have been some potential improvements thrown around for
is_same_file. If the public API for
same-file is flexible to change without breaking then we don’t need to answer all these questions now.
Are there concrete cases where the approach used in
same_file will produce false positives/negatives? Are these cases common among similar libraries in other ecosystems? Are there alternative approaches that avoid them?
is_same_file return something like an
Option<bool> that captures the confidence that the files are the same?
We don’t want to be basing behaviour on individual file systems to keep the implementation simple and easy to reason about.
If there are concrete edge cases could the docs clarify them and point callers in a different direction? Maybe
same_file isn’t the right crate for their needs.
is_same_file function be made more efficient by eliminating some system calls?
Issues to file against the
- docs: Clarify the statement about false positives a little more. It doesn’t need too much though
- docs: Add examples to public methods on
- docs: Replace
- docs: Add Panic section to methods in
unwrap, or document why the
- docs: Add Errors section to methods that return
- docs: Add hyperlink to source example mentioned in the crate root docs
- docs: Add hyperlinks to types in docs prose
assert_syncmethods and test
- Start tracking release notes for version bumps
inomethods to a platform-specific extension trait
How are we tracking?
- [x] Create evaluation thread based on this template
- [x] Work with author and issue tracker to identify known blockers
- [x] Compare crate to guidelines by filling in checklist
- [x] Record other questions and notes about crate
- [x] Draft several use case statements to serve as cookbook examples
- [x] Record recommendations for updated guidelines
- [x] Create new issues and tracking issue on crate’s issue tracker
- [x] Solicit use cases for cookbook examples related to the crate
- [x] File issues to implement cookbook examples
- [ ] File issues to update guidelines
- [ ] Post all approachable issues to TWiR call for participation thread
- [x] Update links in coordination thread