This guidance applies to changes to the skeleton project itself. Because the skeleton’s history is merged into each of its downstream consumers, contributions here carry extra constraints.
The source for this page lives on the gh-pages branch of jaraco/skeleton (as skeleton-contrib.md); the rendered form is published at https://blog.jaraco.com/skeleton.
The skeleton carries no tests or checks of its own. More broadly, most of the machinery it provides — tox, towncrier, the CI checks — does not apply to the skeleton itself; those features exist to serve downstream projects. To validate a change, apply it to a real downstream project first, then port (or cherry-pick) the commit back to the skeleton.
The skeleton keeps no changelog of its own, so its history is conveyed entirely through its commit messages. Treat each message as the durable, user-facing record of what changed and why.
Always squash merge pull requests. Every commit on the skeleton’s main branch is inherited by every downstream project, so collapsing each change to a single commit keeps that shared history as small and legible as possible.
Always use repo-qualified references in commit messages and any tracked file (code comments, configuration, etc.) — for example jaraco/skeleton#123, never a bare #123. Because these commits are merged into downstream projects, a bare reference would resolve against the wrong repository and notify unrelated issues. See Commit Integrations Mismatch for rationale.
The skeleton’s issue tracker covers both defects in the skeleton implementation and systemic problems common to its downstream projects — even when the latter cannot be resolved in the skeleton itself.
Avoid news fragments in the skeleton. A fragment added here propagates to every downstream project on merge, and the skeleton can only remove it once all of them have rendered and deleted their copies — remove it any sooner and late-syncing projects never receive it. That is an unbounded coordination burden.
If a fragment is truly unavoidable, it must be anonymous (a + filename). A numbered fragment makes towncrier emit a bare #N that resolves against each downstream repository rather than the skeleton, and — per the rule above — a fragment cannot carry a repo-qualified reference.
This project does not include a .gitignore module or provides a very minimal one because this project holds the philosophy that it’s preferable to specify ignores at the most relevant level, and so .gitignore for a project should specify elements unique to that project and not elements peculiar to the language or system or user.
Instead, skeleton recommends users to implement ignores for the language(s), system, and user in the development environment. For example, jaraco has the following in ~/.gitconfig:
[core]
excludesfile = ~/.gitignore_global
Referencing this .gitignore_global.
As you can see, this file contains all of the commonly encountered ignorables when developing node.js and Python projects using PyCharm or emacs or git on all the common platforms. This simple configuration, linked in each development environment, avoids the need to configure (and sync) each downstream project with the aggregate configuration of jaraco’s environments and the environments of each of the contributors to each of the projects the contributiors may touch.
It’s not a perfect alignment of concerns to projects, but it’s a dramatically simpler approach saving hundreds of commits that can be readily adopted by any user and is strongly recommended for skeleton-based projects.
See gitignore docs for more details regarding configuring ignore files. For users only incidentally involved with skeleton-derived projects, consider downloading jaraco’s .gitignore_global to the checked-out project:
wget https://raw.githubusercontent.com/jaraco/dotfiles/main/.gitignore_global -O - >> .git/info/exclude
Note: See dotfiles for guidance on applying these settings in GitHub Codespaces.