Start Using action

[devlinjunker]

Is your feature request related to a problem? Please describe:
I always forget follow through with all of the changes needed when forking/cloning this project, so when I look through the documentation of a forked project there are sections that aren’t relevant.

Describe the solution:
can we have an action that runs when the first commit is created

• adds issues for each step/file we can change so we can close them as we do them?

Describe alternatives you've considered:

• PRs maybe? with custom checklists to be completed before it can be merged?

Links/Additional context:
..

Testing:
..

[devlinjunker]

Here is a guide from claude:

# Template Conversion Guide
**Converting template.github.semver to a New Project**

This document outlines all steps needed to convert this GitHub template into a new project. Use this as a reference for manual conversion or as a basis for automation scripts.

---

## Overview

The template provides semantic versioning workflows, git hooks, and documentation structure. Converting to a new project requires:
1. Updating documentation and metadata
2. Cleaning git history and tags
3. Configuring remotes and branches
4. Setting up project-specific content

---

## Step 1: Initial Repository Setup

### Option A: Using GitHub Template Feature (Recommended)
```bash
# Use GitHub UI "Use this template" button
# This creates a new repo with clean history automatically

Option B: Clone and Reset

# Clone the template
git clone --depth 1 -b develop https://github.com/devlinjunker/template.github.semver.git
mv template.github.semver <new-project-name>
cd <new-project-name>

# Keep template remote for future updates
git remote rename origin template
git config remote.template.tagopt --no-tags

# Unset upstream tracking
git branch --unset-upstream develop

---

Step 2: Update Documentation Files

Files to Update with Project-Specific Information:

README.md

Replace the following sections:

• Version: Change from 1.8-SNAPSHOT to 0.1-SNAPSHOT
• Title: Change from template name to your project name
• Logo: Remove logo reference or update path
• Badges: Update all URLs from devlinjunker/template.github.semver to your repo
• CII Badge: Remove or update project ID
• Intro: Replace template description with your project description
• Dependencies: Add your project-specific dependencies/frameworks
• Setup Instructions: Remove template instructions, add your setup steps
• Links: Update repository URLs in footer references

Automated Pattern:

# Find and replace pattern
OLD_REPO="devlinjunker/template.github.semver"
NEW_REPO="<username>/<new-repo-name>"
sed -i '' "s|${OLD_REPO}|${NEW_REPO}|g" README.md

CONTRIBUTING.md

• Update issue reporting URL
• Remove "Create your own Project from this Template" section
• Remove "Update a Project" section with template remote instructions
• Add project-specific environment setup
• Update all GitHub URLs from template to new repo

CHANGELOG.md

• Update release URL from template to new repo

SECURITY.md

• Update issue submission URL
• Reset version support table for new project (start with 0.x)

LICENSE

• Update copyright year to current year
• Update copyright holder if different
• Change license type if needed (MIT to Proprietary, etc.)

CODE_OF_CONDUCT.md

• Generally no changes needed (standard Contributor Covenant)
• Optionally update contact information

Template for Documentation Updates:

// Pseudocode for automation
const updates = {
  'README.md': [
    { pattern: /Version: [\d.]+-SNAPSHOT/, replace: 'Version: 0.1-SNAPSHOT' },
    { pattern: /# Template.*/, replace: '# <NEW_PROJECT_NAME>' },
    { pattern: /devlinjunker\/template\.github\.semver/g, replace: '<USER>/<REPO>' },
    { pattern: /https:\/\/img\.shields\.io\/cii\/.*/, replace: '' }, // Remove CII badge
    { section: 'Intro', replace: '<PROJECT_DESCRIPTION>' },
    { section: 'Dependencies', add: '<PROJECT_DEPENDENCIES>' }
  ],
  'CONTRIBUTING.md': [
    { removeSection: 'Create your own Project from this Template' },
    { removeSection: 'Update a Project' },
    { pattern: /devlinjunker\/template\.github\.semver/g, replace: '<USER>/<REPO>' }
  ],
  'CHANGELOG.md': [
    { pattern: /devlinjunker\/template\.github\.semver/g, replace: '<USER>/<REPO>' }
  ],
  'SECURITY.md': [
    { pattern: /devlinjunker\/template\.github\.semver/g, replace: '<USER>/<REPO>' },
    { section: 'versionTable', replace: 'simple0.x-only-table' }
  ],
  'LICENSE': [
    { pattern: /Copyright \(c\) \d{4}/, replace: `Copyright (c) ${new Date().getFullYear()}` },
    { pattern: /Copyright holder/, replace: '<YOUR_NAME>' }
  ]
};

---

Step 3: Remove Template Assets

Files/Directories to Remove:

# Remove logo files
rm -rf img/

# These are template-specific, remove if not needed:
# (Keep if you want the template infrastructure)
# - .github/workflows/* (review and keep what's needed)
# - scripts/release/* (if not using semver automation)

Files to Keep:

• .github/workflows/ - Version control workflows (modify as needed)
• .github/ISSUE_TEMPLATE/ - Issue templates (customize)
• scripts/hooks/ - Git hooks (customize)
• .bulldozer.yml - Auto-merge config (customize)
• .gitmessage - Commit message template

---

Step 4: Clean Git History

Delete Old Tags

# Delete all template tags locally
git tag | xargs -n 1 git tag -d

# Configure template remote to never fetch tags
git config remote.template.tagopt --no-tags

Reset Git History (Creates Clean Slate)

# Create orphan branch with current state
git checkout --orphan new-start

# Add all files
git add -A

# Create initial commit (use --no-verify to bypass branch name hook)
git commit --no-verify -m "Initial commit for <PROJECT_NAME>

- <Brief description>
- Version 0.1-SNAPSHOT
- <Key features/architecture notes>"

# Replace old develop branch
git branch -D develop
git branch -m develop

Alternative: Keep Template History

# If you want to preserve template history:
# Just commit your changes normally
git add -A
git commit -m "chore: convert template to <PROJECT_NAME>"

---

Step 5: Set Up Git Hooks

# Create symbolic links for git hooks
ln -sf ../../scripts/hooks/commit-msg.sh .git/hooks/commit-msg
ln -sf ../../scripts/hooks/post-commit.sh .git/hooks/post-commit
ln -sf ../../scripts/hooks/pre-commit.sh .git/hooks/pre-commit
ln -sf ../../scripts/hooks/pre-push.sh .git/hooks/pre-push

# Verify hooks are linked
ls -la .git/hooks/ | grep -E "(commit-msg|post-commit|pre-commit|pre-push)"

---

Step 6: Configure Remote Repository

Create GitHub Repository

1. Create new repository on GitHub
2. Do NOT initialize with README (we have our own)
3. Set visibility (public/private)
4. Add description

Add Remote and Push

# Add your remote
git remote add origin https://github.com/<username>/<new-repo-name>.git

# Push develop branch
git push -u origin develop

# Verify remotes
git remote -v
# Should show:
#   origin   <your-repo-url> (fetch/push)
#   template <template-url> (fetch/push)

---

Step 7: GitHub Configuration

A. Enable GitHub Actions

1. Go to repository Settings > Actions > General
2. Allow all actions
3. Save

B. Add Required Secrets

# Generate a Personal Access Token (PAT):
# GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
# Scopes needed: repo, workflow

Add to repository secrets:

• GH_PAT or GITHUB_TOKEN - For wiki sync and release actions

C. Create Labels

1. Go to Actions tab
2. Find "Manage Labels" workflow
3. Run workflow manually
4. Verify labels created from .github/labels.yaml

D. Enable Bulldozer

1. Visit https://github.com/apps/prylabs-bulldozer
2. Install app
3. Grant access to your repository
4. Test with PR using !merge comment

E. Optional: Branch Protection

Settings > Branches > Add rule:

• Branch name pattern: main or develop
• Require pull request reviews
• Require status checks to pass
• Require branches to be up to date

F. Optional: Enable Dependabot

Security > Dependabot > Enable

---

Step 8: Create Main Branch (When Ready)

# When ready for first production release
git checkout -b main
# Update version in README to 0.0.0
git add README.md
git commit -m "chore: initialize main branch"
git push -u origin main

# Set main as default branch on GitHub
# Settings > Branches > Default branch > Change to main

---

Automation Script Template

#!/bin/bash
# template-converter.sh
# Automates conversion of template to new project

set -e

# Configuration
NEW_REPO_NAME="$1"
NEW_REPO_OWNER="$2"
PROJECT_DESCRIPTION="$3"

if [ -z "$NEW_REPO_NAME" ] || [ -z "$NEW_REPO_OWNER" ]; then
    echo "Usage: $0 <repo-name> <owner> <description>"
    exit 1
fi

echo "Converting template to: ${NEW_REPO_OWNER}/${NEW_REPO_NAME}"

# Step 1: Update documentation
echo "Updating documentation..."
OLD_REPO="devlinjunker/template.github.semver"
NEW_REPO="${NEW_REPO_OWNER}/${NEW_REPO_NAME}"
CURRENT_YEAR=$(date +%Y)

# Update README
sed -i '' "s|Version: [0-9.]*-SNAPSHOT|Version: 0.1-SNAPSHOT|" README.md
sed -i '' "s|# Template - Semantic Versioning with Github|# ${NEW_REPO_NAME}|" README.md
sed -i '' "s|${OLD_REPO}|${NEW_REPO}|g" README.md
sed -i '' '/shields.io\/cii\/summary/d' README.md
sed -i '' '/<img.*logo-small.png/d' README.md

# Update CONTRIBUTING
sed -i '' "s|${OLD_REPO}|${NEW_REPO}|g" CONTRIBUTING.md

# Update CHANGELOG
sed -i '' "s|${OLD_REPO}|${NEW_REPO}|g" CHANGELOG.md

# Update SECURITY
sed -i '' "s|${OLD_REPO}|${NEW_REPO}|g" SECURITY.md

# Update LICENSE year
sed -i '' "s|Copyright (c) [0-9]*|Copyright (c) ${CURRENT_YEAR}|" LICENSE

# Step 2: Remove template assets
echo "Removing template assets..."
rm -rf img/

# Step 3: Clean git history
echo "Cleaning git history..."
git checkout --orphan new-start
git add -A
git commit --no-verify -m "Initial commit for ${NEW_REPO_NAME}

- ${PROJECT_DESCRIPTION}
- Version 0.1-SNAPSHOT"

git branch -D develop 2>/dev/null || true
git branch -m develop

# Step 4: Clean tags and configure remote
echo "Cleaning tags..."
git tag | xargs -n 1 git tag -d 2>/dev/null || true
git remote rename origin template 2>/dev/null || true
git config remote.template.tagopt --no-tags
git branch --unset-upstream develop 2>/dev/null || true

# Step 5: Setup git hooks
echo "Setting up git hooks..."
ln -sf ../../scripts/hooks/commit-msg.sh .git/hooks/commit-msg
ln -sf ../../scripts/hooks/post-commit.sh .git/hooks/post-commit
ln -sf ../../scripts/hooks/pre-commit.sh .git/hooks/pre-commit
ln -sf ../../scripts/hooks/pre-push.sh .git/hooks/pre-push

echo ""
echo "✓ Conversion complete!"
echo ""
echo "Next steps:"
echo "1. Review and update project description in README.md"
echo "2. Add project-specific dependencies"
echo "3. Create GitHub repository: ${NEW_REPO_OWNER}/${NEW_REPO_NAME}"
echo "4. Add remote: git remote add origin <your-repo-url>"
echo "5. Push: git push -u origin develop"
echo "6. Configure GitHub Actions, Labels, and Bulldozer"

---

Verification Checklist

After conversion, verify:

• All documentation URLs point to new repository
• Version is set to 0.1-SNAPSHOT
• Git hooks are linked and working
• No template tags exist (git tag should be empty)
• Template remote configured with --no-tags
• Clean git history with single initial commit (if desired)
• Logo files removed from img/
• LICENSE updated with current year
• Project description added to README
• Setup instructions are project-specific
• Remote repository created on GitHub
• Code pushed to remote
• GitHub Actions enabled
• Labels created
• Bulldozer app installed (optional)

---

Key Files Changed During Conversion

File	Changes
README.md	Version, title, badges, intro, dependencies, setup
CONTRIBUTING.md	URLs, setup instructions
CHANGELOG.md	Release URL
SECURITY.md	Issue URL, version table
LICENSE	Year, holder, license type
img/	Removed entirely
.git/config	Remote configuration, tag options
.git/hooks/*	Symbolic links created

---

Maintenance: Updating from Template

If you kept the template remote, you can pull updates:

# Fetch latest template changes
git fetch template

# Review changes
git diff template/develop

# Cherry-pick specific commits or merge
git cherry-pick <commit-hash>
# OR
git merge template/develop --allow-unrelated-histories

# Resolve conflicts favoring your project-specific changes

---

Notes

• Template history is ~52 commits and ~51 tags
• Git hooks enforce branch naming: <prefix>/<description>
  • Valid prefixes: feature, fix, bug, doc, build, test, refactor, performance, etc.
• Bulldozer auto-merges PRs with !merge comment when CI passes
• Release workflow uses git-mkver to determine version from tags and commits
• Wiki sync happens on merge to main

---

Last Updated: January 2026
Template Version: 1.7.2
Conversion Time: ~15-20 minutes manual, ~2 minutes with script

[devlinjunker]

Notes from using as template for one-word-game repo

Project Setup TODOs

Required Tasks

1. Set up Remote Repository

• Create new repository on GitHub: devlinjunker/one-word-game
• Add origin remote: git remote add origin <your-repo-url>
• Push develop branch: git push -u origin develop
• Verify repository settings and description

2. Create Main Branch

• Create main branch when ready for first production release
• Update version in README to 0.0.0 on main branch
• [ ] Set main as default branch on GitHub
  • Don't want to set this...

3. Configure GitHub Actions

• Create Personal Access Token (PAT) with repo permissions
• Add PAT to repository secrets as GH_PAT or similar
  • I think this should have been PAT as needed by patch-cut.yml, release-cut.yaml and release-on-merge.yaml
  • Needs to have Repository Contents permissions (probably also Pull Requests and Issues)
• Test workflow runs (may need to trigger manually first time)
• [ ] Verify wiki sync action works (initialize wiki first)
  • Doesn't work in private repos

4. Enable Bulldozer App

• Install Bulldozer GitHub app
• Grant access to one-word-game repository
• Verify .bulldozer.yml configuration
• Test auto-merge with a PR (use !merge comment)

5. Create GitHub Labels

• Run the manage-labels GitHub Action manually
• Verify labels from .github/labels.yaml are created
• Review and adjust label configuration if needed

Optional Tasks

6. Branch Protection Rules

• NOTE: Doesn't work private repos
• Set up branch protection for main:
  • Require pull request reviews
  • Require status checks to pass
  • Require branches to be up to date
• Set up branch protection for develop:
  • Require status checks to pass
  • Allow force pushes (for maintainers)

7. Enable Dependabot

• Enable Dependabot alerts in repository settings
• Review .github/dependabot.yml configuration
• Monitor for GitHub Actions updates

8. Initialize Project Structure

• Set up monorepo structure with Turborepo
• Create packages/ directory for shared code
• Set up initial React app in appropriate location
• Configure TypeScript, ESLint, and Prettier
• Add package.json and workspace configuration

Completed ✅

• ✅ Updated all documentation (README, CONTRIBUTING, SECURITY, CHANGELOG)
• ✅ Reset version to 0.1-SNAPSHOT
• ✅ Updated project description and dependencies
• ✅ Added setup instructions
• ✅ Created Git Hooks symbolic links
• ✅ Updated LICENSE to proprietary
• ✅ Removed template logo files
• ✅ Reset git history (single clean commit)
• ✅ Deleted template tags and configured remote
• ✅ Unset develop branch upstream tracking

---

Note: Once the remote repository is set up and you've pushed your code, you can start working on feature branches following the branching conventions enforced by git hooks (e.g., feature/game-setup, build/monorepo-config, etc.).