open-source-prep

name	open-source-prep
description	Prepare an existing project for open-source release — clean repo, add tests/CI/docs, remove personal/env-specific paths, package for distribution.
triggers	["make this project open source","prepare for public release","clean up repo for github","add CI and contributing guide"]

Open-Source Preparation

Systematic checklist for turning an internal project into a public open-source repo.

Pre-flight: Understand the project

1. Read README, pyproject.toml/setup.py, .gitignore, LICENSE
2. git ls-files — what's tracked
3. du -sh on key dirs — find bloat
4. git log --oneline — commit history hygiene
5. Identify the core value (what's the "killer feature"?)

Phase 1: Repo cleanup (P0)

Remove large/generated files from git

# Add to .gitignore FIRST
echo "styles/" >> .gitignore

# Untrack without deleting local files
git rm -r --cached styles/

# Commit
git commit -m "chore: remove generated styles from git"

Pitfall: git rm -r --cached can fail with exit 128 on very large directories (too many args). Fix: use find dir/ -maxdepth 0 -exec git rm -r --cached {} +

Clean personal/env-specific artifacts

• .idea/, .vscode/, .DS_Store → .gitignore
• Agent runtime dirs (.omx/, .hermes/) → .gitignore
• state/, logs/, output/ → .gitignore
• Remove from tracking: git rm -r --cached <dir>

Remove hardcoded personal paths

Search for: ~/.zshenv, ~/.bashrc, ~/.hermes, home directory references. Replace with: environment variables + .env file loading.

# BAD: personal path
zshenv_path = Path.home() / ".zshenv"

# GOOD: env var + .env
env_path = Path(__file__).resolve().parent.parent / ".env"

Keep sample data, remove bulk

• Keep 5-10 curated examples in sample_styles/ or examples/
• Remove the rest (users generate their own)
• Document how to regenerate

Phase 2: Documentation (P0-P1)

README.md (English for international audience)

Structure:

1. One-liner + badges (PyPI, CI, License)
2. Quick Start (3 lines to use the core feature)
3. Full Usage
4. Architecture
5. Contributing link
6. License

Save native-language version as README_zh.md, README_ja.md, etc. Link from main README: [中文](README_zh.md)

CONTRIBUTING.md

• How to set up dev environment
• How to run tests
• How to add content (seeds, plugins, etc.)
• Code style expectations
• PR process

CHANGELOG.md

Keep a changelog. Format: ## [version] — date with Added/Changed/Fixed/Removed.

Phase 3: Testing (P0)

Test the core value first

The most important tests cover the project's unique differentiator. For a tool: test the CLI entry point + core algorithm. For a library: test the public API.

Test pattern for scoring/evaluation tools

class TestDimension:
    def test_positive_case(self):  # should trigger
    def test_negative_case(self):  # should not trigger
    def test_edge_case(self):      # boundary

class TestIntegration:
    def test_clean_input_passes(self):
    def test_bad_input_fails(self):
    def test_score_keys(self):     # output schema

class TestCLI:
    def test_file_input(self):
    def test_stdin(self):
    def test_exit_codes(self):

Validate bundled examples

@pytest.mark.parametrize("example", EXAMPLE_LIST)
def test_example_passes(self, example):
    result = evaluate(example)
    assert result.passes, f"Example '{example}' failed: {result.details}"

Phase 4: CI/CD (P1)

Pitfall refs: See references/ruff-ci-pitfalls.md for ruff format/lint CI failures, Python 3.9 f-string compat, E402/E501 config. See references/github-pages-api-pitfalls.md for enabling Pages via API. See references/css-font-parsing-pitfalls.md for multi-word font name detection. See references/js-emoji-regex-pitfalls.md for JS surrogate pair regex bugs and cache-busting patterns.

GitHub Actions CI

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    strategy:
      matrix:
        python-version: ["3.9", "3.10", "3.11", "3.12"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install -e ".[dev]"
      - run: pytest tests/ -v
  lint:
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff
      - run: ruff check .
      - run: ruff format --check .

GitHub Pages deploy (for galleries/demos)

# .github/workflows/pages.yml
on:
  push:
    branches: [main]
    paths: ["gallery/**"]

Phase 5: Distribution (P1-P2)

pyproject.toml essentials

[project]
name = "your-package"
version = "0.3.0"
license = { text = "MIT" }
requires-python = ">=3.9"

[project.scripts]
your-cli = "src.module:main"

GitHub Action (if your tool is useful in CI)

Create action.yml at repo root. Example: HTML scorer that fails CI if score exceeds threshold.

Docker deployment (static sites / galleries)

Full recipe: See references/docker-static-site-deploy.md for Dockerfile, docker-compose, .dockerignore, and pitfalls.

For projects with a static web component (gallery, docs, demo):

FROM nginx:alpine
COPY gallery/ /usr/share/nginx/html/gallery/
COPY sample_styles/ /usr/share/nginx/html/styles/  # symlink as expected path
RUN echo '<meta http-equiv="refresh" content="0;url=/gallery/">' > /usr/share/nginx/html/index.html
EXPOSE 80

# docker-compose.yml
services:
  app:
    build: .
    ports: ["8004:80"]
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost/health"]

Pitfall: Gallery JS may reference ../styles/ but only sample_styles/ exists. Map the sample dir as /styles/ in the container.

Pitfall: Always add .dockerignore excluding .venv/, .git/, styles/ (bulk generated), tests/ — keeps build context small.

.env.example

# Copy to .env and fill in your keys
API_KEY=your-key-here

Checklist before git push

Create repo and push in one step

gh repo create my-project --public \
  --description "One-line description" \
  --source . --push

Pitfall: Tag pushes via HTTPS may fail with "could not read Username" even when gh auth status shows success. Fix: switch remote to SSH:

git remote set-url origin [e-mail]:OWNER/REPO.git
git push origin v0.1.0

• No files > 1MB in git (except legitimate assets)
• No personal paths in code
• No API keys in code or config
• .gitignore covers: .env, pycache, .venv, IDE dirs, generated output
• LICENSE file present
• README has: install, quick start, contributing link
• Tests pass: pytest tests/ -v
• CI config present
• Sample data/examples included and validated