Why use a skeleton structure?

Many projects start from some kind of template. These define some basic structure, customized with project specific variables, that developers can add their code into. One example of this is cookiecutter.

The problem with this approach is that it is difficult to apply changes to the template into projects that have been cut from it. Individual changes have to be copy/pasted into the code, leading to partially applied fixes and missed updates.

This module takes a different approach, as explained in jaraco’s blog post. It is a repo that can be forked, and updates merged to the skeleton can be merged into projects tracking it with a git pull operation. No more copy/pasting.

Why do you need the commandline tool?

The reason for the commandline tool is because this skeleton module has more code and docs content than jaraco/skeleton. There are numerous references to the repo and package name, so the commandline tool applies a single commit on top of the repo that customizes it to the particular project. Once the initial creation/adoption has occurred however, a simple git pull is sufficient to keep it updated.

What happens if the merges become too difficult?

If projects diverge too much, then merging in changes will become increasingly difficult. This is probably a sign that the approach the project has taken is too different from the skeleton structure for it to be of much benefit. At this point, the merge can be abandoned, the section from CONTRIBUTING.rst deleted, and the project need not pull from the skeleton repo any more.