More docs

README.md

@@ -58,6 +58,36 @@ access to gerrit to be able to unabandon changes, while pulls from upstream
 can be anonymous. Future additions such as watching upstream's event stream
 might require authentication on the upstream side as well.
 
+## Caching opportunities
+
+There are fewer caching opportunities than one might think:
+
+Every run to push changes to downstream needs to newly figure out the root
+changes to apply work streams to because downstream might have changed:
+commits might have been submitted, patches been marked WIP or reordered, ...
+
+However, even though starting from scratch, if not much happened between
+two runs, the scan needn't to go deep into upstream's history (and therefore
+doesn't have to mess with downstream a whole lot). The root change should be
+found pretty soon. For smaller work streams there might be nothing to do at
+all (if no commit matching its specification has been collected while going
+back until a common point in time has been found)
+
+## Limited work streams
+
+With onlyIfTouching configured, finding the right root change to work from
+is slightly more involved than just going back through git history. Once
+finding the old commit that needs to be processed (as determined by gerrit
+metadata in commit messages and commits lining up in upstream and downstream),
+the commit to use as parent needs to be identified.
+
+For this, the next-oldest commit touching any of the `onlyIfTouching`
+paths needs to be used determined, which can be done locally (git log $those
+$paths on upstream history).  The next thing to determine is if that commit
+is already submitted downstream. If not, it becomes the parent commit for
+the work stream.  Otherwise the upstream's parent commit (no matter if it's
+touching any of these files or not) becomes the downstream parent change.
+
 ## Configuration format
 
 Configuration is stored in a single file in yaml format: