Merge pull request #2930 from ghostbuster91/main

Add notes about repository resolution order

doc/docs/other-repositories.md

@@ -36,3 +36,33 @@ It is possible to use a custom Ivy repository and pattern by concatenating them:
 ```
 $ cs fetch --repository  "https://corporate.com/ivy-repo/[org]/[module]/[baseRev](-[folderItegRev])/[module]-[baseRev](-[fileItegRev])(-[classifier]).[ext]" sh.almond:scala-kernel_2.12.8:0.2.2
 ```
+
+## Repository resolution order
+
+The resolution order of the repositories is controlled in coursier by two things - [modes](https://github.com/coursier/coursier/blob/595f7d7d48c0c38bded88531d1fe1cdeb3ccc07c/cli/src/main/scala-2.12/coursier/cli/options/CommonOptions.scala#L13) and [cache policies](https://github.com/coursier/coursier/blob/595f7d7d48c0c38bded88531d1fe1cdeb3ccc07c/cache/jvm/src/main/scala/coursier/CachePolicy.scala).
+
+Modes are tried successively and for each mode, repositories themselves are tried successively.
+
+By [default](https://github.com/coursier/coursier/blob/595f7d7d48c0c38bded88531d1fe1cdeb3ccc07c/cache/jvm/src/main/scala/coursier/CachePolicy.scala#L68), 
+the first policy looks at what's in the cache, only trying to fetch / update the changing things (snapshots…) that are already in cache. 
+
+The second policy only looks at what's already in cache (this one may be redundant with the first one…). 
+
+The third one tries to actually fetch things.
+
+If we have 3 repositories and a dependency is already in cache for the third one, it will be picked in cache from the third repo (by the first two policies). 
+
+Even if the dependency was actually available in the first or second repositories.
+
+For example:
+
+Let's say that we have configured coursier to use following repositories:
+1. maven central
+2. ivy2Local
+3. nexus snapshots
+
+If the dependency is already in the ivy2Local coursier will use it instead of reaching to maven central. 
+
+That trades off some reproducibility (we may get different jars depending on the previous cache state) for less IO overhead (if something is in cache for any of the repositories, no network IO will happen).
+
+