fetch-all-upstreams: integrate cache for /user/repos

[salewski]

Issue #59 introduced the cache which we can now build upon. The ads-github-fetch-all-upstreams program has a common path slow spot when fetching data about all of the user's GitHub repos, which it does prior to doing most of its work. That code path can benefit from using the new cache.

Some prototype code was developed for this purpose alongside the cache implementation, but much needs to be done to make it work "for real".

[salewski]

This issue has been fixed for ads-github-tools-0.3.2.

WORKFLOW BREAKAGE (the good kind): The default behavior of the ads-github-fetch-all-upstreams program has changed to expect that the cached data is present and available. By default, it attempts to access the cached data in 'offline' mode, which is the fastest. This means use user must have successfully run 'ads-github-cache --update' or an error will be emitted due to the cached data not being available.

The pain of this workflow breakage is considered to be very low, and the benefit of the change very high.

The blurb about it from our 'NEWS' file:

*** issue 61: "ads-github-fetch-all-upstreams: integrate cache for /user/repos"

    https://github.com/salewski/ads-github-tools/issues/61

    The 'ads-github-fetch-all-upstreams' program has been enhanced to leverage
    the new ads-github-tools cache.

    _BACKWARD_INCOMPATIBILITY:_ The default behavior of the program has been
    changed in that the offline cached data will be used by default. Users who
    have not yet initialized the cache will see an error:

    :    $ ads-github-fetch-all-upstreams -vcu
    :    ads-github-cache (error): "paged collection" metadata not found in cache for: /user/repos
    :    ads-github-fetch-all-upstreams (error): was unable to obtain /user/repos data from cache; bailing out

    The fix is easy: just update the cache and then rerun:

    :    $ ads-github-cache -v --update
    :    [takes a while the first time]
    :
    :    $ ads-github-fetch-all-upstreams -vcu
    :    [note how fast it is!]

    While manually updating the cache as shown above works well enough for
    very casual usage, if the cache is not up-to-date (enough) then the
    problem still exists that you have wait a painfully long time for
    /something/ to run before ads-github-fetch-all-upstreams does what you
    want it to do.

    What you really want is for the cached data to be ready and waiting, so
    that when you whip out ads-github-fetch-all-upstreams it can operate
    quickly. Toward that end, we expect most users will use a cron job (or
    similar) to update the cache once or twice a day (or maybe less
    frequently).

    There is a new '--cache-mode=MODE' command line option that allows the
    user to select which caching behavior is desired: 'offline' (the default),
    'online', or 'none'.

    If you just want to get the old, slow behavior, say '--cache-mode=none'.

    See ads-github-fetch-all-upstreams(1) for the full scoop.