Blackwell OSS Kit

Open source project templates, best practices, and GitHub repository standards for maintainers

A collection of copy/paste templates, best practice guides, and GitHub rulesets for shipping professional open source projects. Includes README templates, CHANGELOG formats, CONTRIBUTING guides, SECURITY policies, branch protection rules, and documentation standards.

What This Is

1. Reference Short guides explaining:

   • semantic versioning expectations
   • changelog discipline
   • release hygiene
   • security basics
   • governance options

2. Templates Drop-in files you can copy into any repo:

   • README
   • CHANGELOG
   • CONTRIBUTING
   • SECURITY
   • SUPPORT
   • ROADMAP
   • GOVERNANCE
   • PR + Issue templates

Why This Exists

Many open source projects struggle with the basics:

• unclear contribution path
• no security contact
• no release discipline
• no stable versioning rules
• incomplete README expectations

This kit exists to make "good defaults" effortless.

Quick Use

Copy the templates you want:

# from your project root
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackwell-oss-kit/main/templates/README.template.md -o README.md
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackwell-oss-kit/main/templates/CHANGELOG.template.md -o CHANGELOG.md
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackwell-oss-kit/main/templates/CONTRIBUTING.template.md -o CONTRIBUTING.md
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackwell-oss-kit/main/templates/SECURITY.template.md -o SECURITY.md

(Replace blackwell-systems with your org/user once published.)

Suggested "Serious OSS Minimum"

If you want the simplest credible baseline, include:

• README.md
• LICENSE
• CHANGELOG.md
• CONTRIBUTING.md
• SECURITY.md
• Pull request template
• Issue templates

Documentation with Docsify

For projects that grow beyond a single README, we recommend Docsify for documentation sites:

Why Docsify?

• No build step - Runs entirely in browser
• Markdown files - Keep docs in your repo
• Zero config - Works out of the box
• GitHub Pages ready - Deploy instantly
• Themeable - Easy to brand

Example Projects Using Docsify

• Vaultmux - Multi-vault secret management
• Dotfiles - Dotfiles management framework

See Docsify documentation for themes, plugins, and advanced features.

Roadmap

• v0.1: Reference + templates
• v0.2: Language-specific add-ons (Go, Rust, Python)
• v0.3: GitHub Actions snippets (CI + release helpers)
• v1.0: Optional integration into a scaffold CLI

License

Use whatever license you want for your own repos. This kit's content is intended to be copied and adapted.

Claude Code Skill

This repository includes a Release Engineer skill for Claude Code that helps automate and guide the release process:

Skill: .claude/skills/release-engineer.md

Invoke with: @release-engineer or via the skills menu in Claude Code

Capabilities:

• Guides through semantic versioning decisions
• Updates CHANGELOG.md with proper formatting
• Creates git tags with release notes
• Builds and verifies release artifacts
• Publishes to package registries
• Creates GitHub releases
• Provides rollback procedures

Perfect for maintaining consistent release quality across projects.

Contents

Reference

• docs/principles.md
• docs/versioning.md
• docs/changelog.md
• docs/releases.md
• docs/governance.md
• docs/branch-protection.md

Templates

• templates/*.template.md

GitHub Templates

• .github/

Branch Protection Rulesets

• rulesets/ - Ready-to-import JSON rulesets

Claude Skills

• .claude/skills/release-engineer.md - Release automation guide

Maintainer

Blackwell Systems Opinionated, minimal, and built for real-world maintainers.