Add Section on Jetpack sites

client/state/themes/README.md

@@ -6,6 +6,7 @@ When working with `themes` state, it is helpful to bear some assumptions in mind
 1. The relevant REST API endpoints return the same list of themes for any given WordPress.com site.
    There is also a site-agnostic endpoint, which we hence use to obtain that list once, and
    reuse it for any WP.com site.
+2. The same isn't true for Jetpack sites, so we need to store lists of themes on a per-site basis there.
 
 The themes state looks roughly like this (omitting less relevant parts):
 
@@ -37,3 +38,18 @@ The value corresponding to each key is a [`ThemeQueryManager`](../../lib/query-m
 
 The `activeThemes` subtree contains one entry for each site a user has (no matter if hosted on WordPress.com, or a Jetpack-connected, self-hosted site). Its keys are the numerical `siteId`s, while the values are `themeId` strings.
 Arguably, this duplicates information that is also found in the `sites` subtree (in `sites.items[ siteId ].options.theme_slug`). However, due to the way theme activation works (in particular after a premium theme is purchased), we've found that relying on that state is unreliable for our purposes.
+
+Jetpack Sites
+-------------
+
+Jetpack sites come with a REST API endpoint that triggers installation of a theme from either WordPress.org, or WordPress.com. To tell Jetpack which of either repository to use, we append a `-wpcom` suffix for WP.com themes. The suffix is then also present in the installed theme's ID (and directory name). There's another reason for that, which is to avoid collisions with existing themes in the WordPress.org repository -- otherwise, the WP.com theme would get overridden with a WP.org one of the same name by the self-hosted site's updater. Instead, downloaded WP.com themes include a little plugin that updates them from WP.com.
+
+## Automated Transfer
+
+There's one exception to this, which is Automated Transfer (AT) sites. While handled through Jetpack, the `-wpcom` suffix is absent from installed themes there, mostly to facilitate transfer of theme options from WordPress.com. The WordPress core updater isn't of any concern there. Instead, AT itself manages WP.com themes to be always up-to-date.
+
+## Filtering of WP.com Themes on Jetpack Sites
+
+Since our UI for Jetpack sites consists of an 'Uploaded Themes' and a 'WordPress.com Themes' list and we don't want to duplicate themes between them, we filter WP.com themes from a given Jetpack site's installed themes. Unfortunately, we cannot wholly treat this as an implementation detail at view level and filter there (after getting themes from Redux state), but have to do this right after receiving a themes list from the endpoint, in our `requestThemes()` action, _before_ storing it in Redux state (via `ThemeQueryManager`).
+
+The reason is that `ThemeQueryManager` stores themes lists of fixed length for pagination reasons. Filtering themes from those lists when reading _from_ state would change those lengths and mess up pagination.