From 2667241f44fed464948cbd140bed1b17cfe4e826 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sat, 12 Dec 2020 23:29:03 -0500 Subject: Update skeleton description to describe the periodic collapse. Fixes #27. --- skeleton.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) 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: -- cgit v1.2.1