Shards: Add explanatory comment in shard.lock
I just stumbled upon #130 which was kind of resolved by adding a note to the README.
Having a lock file is quite common with other dependency managers as well, but people who are not familiar with the concept will probably have difficulties understanding what this file is for. Even if the README and man page explain this, it would probably be a nice addition if the shard.lock file had a comment about this as well. It's a YAML file, so it's shouldn't be an issue putting a comment at the top.
straight-shoota
All 7 comments
:+1: just a small comment header with a link
RX14
on 18 Mar 2018
I do't want to clutter lock files with the same message over and over again.
ysbaddaden
on 19 Mar 2018
@ysbaddaden why not? What's the downside of having a short comment pointing users to the purpose of this file?
straight-shoota
on 19 Mar 2018
@ysbaddaden it'd be a single yaml comment, as easy as
io << "# Do not edit or delete this file, see: https://...\n"
lock.to_yaml(io)
Because:
- shards aims for reproducible installs (i.e. resolved versions must be locked somewhere);
- lock file is common in package managers (e.g. bundler, cargo, even yarn, ...);
- it's one quick search in documentation in the case you're not familiar with it.
If the information can't be found easily: fix documentation, don't clutter the lockfile with a useless message that will be repeated again an again.
ysbaddaden
on 19 Mar 2018
That logic is probably not understood by all users. Making it easily discoverable would be helpful. Not every package manager uses lock files and not everybody is familiar with package managers.
Automatically generated files are often annotated with a notice about it's purpose and to avoide manual editing.
One line that points people at the documentation of this file is hardly clutter with a useless message. It's certainly not necessary for everyone (if you know what it is for) but it's a little improvement in terms of usability and helps getting new people on board.
straight-shoota
on 19 Mar 2018
And it's going to stay constant so it never shows up in diffs. You literally never have to worry about it.
RX14
on 19 Mar 2018
Related issues
j8r
路
6Comments
stakach
路
4Comments
ysbaddaden
路
3Comments
kostya
路
3Comments
InstanceOfMichael
路
5Comments
Most helpful comment
That logic is probably not understood by all users. Making it easily discoverable would be helpful. Not every package manager uses lock files and not everybody is familiar with package managers.
Automatically generated files are often annotated with a notice about it's purpose and to avoide manual editing.
One line that points people at the documentation of this file is hardly clutter with a useless message. It's certainly not necessary for everyone (if you know what it is for) but it's a little improvement in terms of usability and helps getting new people on board.