Well, in Cargo.toml vs Cargo.lock, you can find this "When in doubt, check Cargo.lock into the version control system (e.g. Git)." I can not understand this at once when i see it, especially i am translating it into Chinese. So is there anyone of you who can tell me how should I understand it? 
can you be more specific about which terminology or phrase you don't understand? "check ... into ..." means adding the file to the repository, making it under the control of git. is that the phrase you have problem understanding?
I mean, this sentence just added next to the differences between Cargo.lock and Cargo.toml, and it begins with "when in doubt". So why should I add the lock into git and what is the doubt. It seems that this paragraph has nothing to do with previous one, isn't it?
well, and my english is poor, so if my words confuse you, i'd say sorry.
Typical use of version control is to store source files. I think your missing it is implied that Cargo.toml would be added. Cargo.lock on the other hand is machine generated so can be perceived as not belonging. You should not take the paragraph as part of the summary. "Let’s dig in a little bit more." does give a false impression.
If you keep reading:
Sound good? Well, there’s one problem: If you build this package today, and then you send a copy to me, and I build this package tomorrow, something bad could happen. There could be more commits to
regexin the meantime, and my build would include new commits while yours would not. Therefore, we would get different builds. This would be bad because we want reproducible builds.
Which is why you may want to have Cargo.lock in Git version control.
In other words, it is useful to make sure other devs use the same versions of dependencies and depencies of dependencies than you.
Your English is quite clear. I will try to help you with the phrase “when in doubt”. “In doubt” is an English idiom, which if written in more words would be “when [you are] in doubt [about what choice to make]”. In this case, the phrase means: “if you have read this text and are still uncertain about what to do, then put Cargo.lock in version control”.
2 Likes
Yes, I totally agree with you, so this paragraph will be better if it was put after importance and usage of this lock file, i think. And comparaing with the previous words:
If you’re building a non-end product, such as a rust library that other rust
packages will depend on, putCargo.lockin your
.gitignore. If you’re building an end product, which are executable like
command-line tool or an application, or a system library with crate-type of
staticliborcdylib, checkCargo.lockintogit. If you're curious
about why that is, see
"Why do binaries haveCargo.lockin version control, but not libraries?" in the
FAQ.
It is understandable and clear since I can get "what should I do for my lock file" and the reason from this paragraph instead of those words begins with a unclear "doubt" which looks like a puzzle.
I am just complaining about this unclear document, and, thanks for your help.
Thanks for your apperiation!
What confuses me is what the doubt is, and why the reader will be in doubt. You can see that there is only differences between the Cargo.toml and Cargo.lock in usage and functions. So I am just unsatisfied with the coherence about this document and I do think it is worse than the previois version. 
That is one way, yes. But another interpretation is that they are trying to say: if you arrive here because you are quite lost, then it may be best to add the lock to version control. (Or in a more cryptic way "as a rule of thumb add it", or "as a general rule, you are better off adding it.")
I think some docs try to have a catch all or general rule at the beginning so you dont have to read all the file.
Does it make sense?
Yes, and your explanation is very clear, what I am usually thinking is how to make a passage more understandable but, as you mentioned here,
is indeed what a dictionary should do, and this cargo doc will be such a dictionary.
1 Like