Skip to content

template-guide.md

Latest commit

 

History

History
251 lines (168 loc) · 11.5 KB

template-guide.md

File metadata and controls

251 lines (168 loc) · 11.5 KB
Raw

Template Customization Guide

This guide provides detailed instructions for customizing the Liatrio Open Source Template for your project.

Customization Checklist

After creating your repository from this template, choose one of the following customization paths:

Path 1: AI-Guided Customization (Recommended)

Use an AI assistant to guide you through the customization process:

  1. Use the customization prompt: Provide the AI with the prompt at prompts/repository-template-customizer.md
  2. Provide required arguments:
    • target_repository: Your repository (GitHub URL, org/repo, or local path)
    • project_name: Your project name
    • project_description: One-sentence project description
    • primary_language: Your primary language/framework (optional)
    • customization_goals: Optional priorities (optional)
  3. Follow the AI's guidance: The AI will guide you through each customization step, validate changes, and ensure completeness
  4. Review the customization plan: The AI generates a customization-plan.md file documenting all changes made and listing any remaining customization steps.

Example usage:

Run `gh api repos/liatrio-labs/open-source-project-template/contents/prompts/repository-template-customizer.md -q '.content' | base64 -d` to read the prompt then follow its instructions. Use the current directory as the target_repository, 'My Project Name' as the project_name, 'A description of my project' as the project_description, and 'Node.js' as the primary_language. Incorporate these additional goals: <your custom goal 1>, <your custom goal 2>

The AI will handle the entire customization process, including:

  • Updating repository identity and metadata
  • Customizing CI/CD workflows for your language
  • Updating documentation files
  • Removing template-specific content (including CHANGELOG.md and cleaning up docs/repository-settings.md)
  • Installing and validating pre-commit hooks
  • Auditing and updating GitHub settings
  • Verifying GitHub App installations

Review the prompt to get more detail about how it works and the actions it will instruct the AI to perform.

After Customization - Run the Audit:

Once you've completed customization and your repository is in a good state for your project, have your AI assistant run the audit prompt to verify compliance and identify any remaining gaps:

Run `gh api repos/liatrio-labs/open-source-project-template/contents/prompts/repository-template-audit.md -q '.content' | base64 -d` to read the prompt then follow its instructions. Use the current directory as the target_repository and 'liatrio-labs/open-source-project-template' as the template_repository.

The audit will check for missing template files, configuration drift, CI/CD workflow health, repository settings alignment, and documentation completeness. See prompts/repository-template-audit.md for detailed audit methodology.

Path 2: Manual Customization

Follow the checklist below to customize your repository manually:

Repository Configuration

  • Update repository name and description in GitHub settings
  • Update README.md with your project name, description, and badges
  • Update .github/chainguard/main-semantic-release.sts.yaml with your repository path
  • Review and customize .gitignore for your language/framework
  • (Optional) Change license - see Changing the License

CI/CD Workflows

  • Update .github/workflows/ci.yml workflow name if needed
  • Add language-specific setup steps (Node.js, Python, Go, Rust, Java, etc.)
  • Replace placeholder test and lint commands with your actual commands
  • Update paths-ignore in workflows if needed
  • Review .github/workflows/release.yml and customize build/release steps

Pre-commit Hooks

  • Review .pre-commit-config.yaml and add language-specific hooks
  • See CONTRIBUTING.md for examples (ESLint, Ruff, golangci-lint, etc.)
  • Configure hook versions to match your project's requirements

Documentation

  • Update README.md with project-specific information
  • Customize CONTRIBUTING.md with project-specific contribution guidelines
  • Update CODE_OF_CONDUCT.md with project-specific reporting contacts and enforcement owners
  • Review and update issue templates in .github/ISSUE_TEMPLATE/
  • Customize pull request template in .github/pull_request_template.md
  • Update docs/development.md with project-specific setup instructions
  • Remove CHANGELOG.md (if present) - semantic-release will generate a new one based on your commits
  • Remove or update docs/repository-settings.md - this file contains template-specific repository settings guidance and should be cleaned up after customization

Secrets and Authentication

The following secrets are configured at the Liatrio organization level:

  • Verify Octo STS is configured (for semantic-release workflow)
  • Verify Renovate Bot GitHub App is installed (if .github/renovate.json exists)

See Required GitHub Secrets for details.

Repository Settings

  • Enable branch protection for main branch
  • Configure required status checks (CI workflows)
  • Set up CODEOWNERS file if needed
  • Review repository settings (Issues, Wikis, Discussions, etc.)

See docs/development.md for recommended repository settings.

Post-Customization Verification

After completing manual customization and getting your repository in a good state, have your AI assistant run the audit prompt to verify compliance:

Run `gh api repos/liatrio-labs/open-source-project-template/contents/prompts/repository-template-audit.md -q '.content' | base64 -d` to read the prompt then follow its instructions. Use the current directory as the target_repository and 'liatrio-labs/open-source-project-template' as the template_repository.

The audit will identify any remaining gaps, configuration drift, or compliance issues. See prompts/repository-template-audit.md for detailed audit methodology.

Features

Quality Automation

Pre-commit hooks enforce quality standards before code is committed:

  • YAML syntax validation
  • Markdown linting
  • Conventional Commits validation
  • Trailing whitespace removal
  • End-of-file fixes

Add language-specific hooks for your project (linting, formatting, testing) by editing .pre-commit-config.yaml.

CI/CD Pipelines

GitHub Actions workflows automate testing, linting, and releases:

  • ci.yml: Runs tests and linters on every push and pull request
  • release.yml: Automated semantic versioning and changelog generation

Semantic Versioning

Automated releases using semantic-release:

  • Analyzes commits using Conventional Commits
  • Bumps version automatically (major.minor.patch)
  • Generates CHANGELOG.md
  • Creates GitHub releases

Note: This template starts at v0.1.0 for demonstration. When starting your project:

  1. Delete existing tags: git tag -d $(git tag -l)
  2. Remove CHANGELOG.md if it exists
  3. Your first release will start at the appropriate version based on your commit types

Automated Dependency Management

Renovate Bot keeps dependencies up to date with conservative, controlled updates:

  • Automatically creates pull requests for dependency updates
  • Conservative configuration: no auto-merge, manual review required
  • Rate-limited to prevent PR spam (prHourlyLimit: 2, prConcurrentLimit: 10)
  • Scheduled updates run before 3am on Mondays (Pacific time)
  • Dependency dashboard provides overview of all updates

Installation:

  1. Install the Renovate Bot GitHub App
  2. Choose "All repositories" or "Select repositories" for your organization
  3. Renovate will automatically detect the configuration file at .github/renovate.json
  4. An onboarding PR will be created to confirm configuration

Verification:

To verify Renovate Bot is installed and active:

  • Using GitHub CLI:
    • Check for Renovate-created PRs: gh pr list --author "renovate[bot]" --limit 1
    • Check organization installations: gh api orgs/{org}/installations and filter for Renovate app by app_slug: renovate
  • Using GitHub Web UI:
    • Go to Repository Settings → Integrations → GitHub Apps
    • Verify "Renovate" appears in the installed apps list
    • Or check for PRs created by renovate[bot] user

Note: If .github/renovate.json exists but Renovate Bot is not installed, Renovate will not create dependency update PRs. Ensure the GitHub App is installed for Renovate to function.

Configuration:

The template includes a conservative Renovate configuration at .github/renovate.json that:

  • Extends config:recommended with conservative overrides
  • Requires manual review for all updates (no auto-merge)
  • Routes all PRs to @liatrio-labs/liatrio-labs-maintainers for review
  • Groups updates by type (major vs. minor/patch)
  • Limits PR creation rate to prevent overwhelming maintainers

For detailed configuration research and rationale, see docs/specs/02-spec-repository-infrastructure-improvements/RENOVATE-RESEARCH.md.

Note: Renovate uses a GitHub App for authentication and does not require any secrets to be configured.

Template Audit Automation

Repository Auditing helps keep downstream repositories in sync with template updates:

  • Comprehensive compliance checking against template standards
  • Identifies missing files, configuration drift, and compliance gaps

Manual Audit (AI Prompt):

For audits, use the AI prompt directly:

  1. Use the prompt at prompts/repository-template-audit.md
  2. Provide target_repository argument (required)
  3. Optionally provide template_repository argument (defaults to template)
  4. The prompt performs comprehensive file presence and content comparison audits

Audit Scope:

The audit checks:

  • Infrastructure files (.pre-commit-config.yaml, .gitignore, LICENSE)
  • GitHub configuration (.github/CODEOWNERS, .github/SECURITY.md, issue/PR templates)
  • Workflow files (CI, release)
  • Release configuration (Chainguard STS, semantic-release)
  • Documentation (README, CONTRIBUTING, development docs)

For detailed audit methodology, see prompts/repository-template-audit.md.

Required GitHub Secrets

The following secrets must be configured at the organization level (already set up for Liatrio repositories):

Octo STS (Chainguard)

Required for semantic-release workflow authentication (.github/workflows/release.yml).

  • Configured at the organization level via Chainguard Octo STS
  • Provides short-lived tokens for GitHub Actions workflows
  • Configuration file: .github/chainguard/main-semantic-release.sts.yaml
  • Important: Update the subject_pattern in this file to match your repository

Changing the License

This template uses the Apache License, Version 2.0 by default. To change the license:

  1. Delete the existing LICENSE file
  2. Add your preferred license file (MIT, BSD, GPL, etc.)
  3. Update the license badge in your README.md
  4. Update copyright attributions in source files if applicable

Common license resources: