Update skeleton description to describe the periodic collapse. Fixes #27.

1 files changed, 20 insertions, 0 deletions

diff --git a/skeleton.md b/skeleton.md
index ec421c2..dd8ec01 100644
--- a/skeleton.md
+++ b/skeleton.md
@@ -46,6 +46,26 @@ For example, here's a session of the [path project](https://pypi.org/project/pat
 
 Thereafter, the target project can make whatever customizations it deems relevant to the scaffolding. The project may even at some point decide that the divergence is too great to merit renewed merging with the original skeleton. This approach applies maximal guidance while creating minimal constraints.
 
+## Periodic Collapse
+
+In late 2020, this project [introduced](https://github.com/jaraco/skeleton/issues/27) the idea of a periodic but infrequent (O(years)) collapse of commits to limit the number of commits a new consumer will need to accept to adopt the skeleton.
+
+The full history of commits is collapsed into a single commit and that commit becomes the new mainline head.
+
+When one of these collapse operations happens, any project that previously pulled from the skeleton will no longer have a related history with that new main branch. For those projects, the skeleton provides a "handoff" branch that reconciles the two branches. Any project that has previously merged with the skeleton but now gets an error "fatal: refusing to merge unrelated histories" should instead use the handoff branch once to incorporate the new main branch.
+
+```
+$ git pull https://github.com/jaraco/skeleton 2020-handoff
+```
+
+This handoff needs to be pulled just once and thereafter the project can pull from the main head.
+
+The archive and handoff branches from prior collapses are indicate here:
+
+| refresh | archive         | handoff      |
+|---------|-----------------|--------------|
+| 2020-12 | archive/2020-12 | 2020-handoff |
+
 # Features
 
 The features/techniques employed by the skeleton include: