CLAUDE

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the wiki repository for the spellcheck-github-actions GitHub Action. It contains documentation about the action's versioning policy, development process, testing procedures, and release workflows. Unlike a typical code repository, this is purely documentation (Markdown files).

Repository Structure

• Home.md — Main page documenting the sunset policy and versioning strategy. Contains the critical Gantt chart showing when each version is available/sunset.
• Development.md — Instructions for building Docker images locally, with platform-specific notes for Apple Silicon (M1).
• Testing.md — How to test the action's entrypoint using shell scripts, Docker, or pushed images.
• Releasing.md — Complete release checklist and process, including Docker image pushing and GitHub Marketplace publishing.
• Versioning.md — Documentation on version numbering strategy.
• Container-Repositories.md — Information about Docker container repositories.
• _Sidebar.md & _Footer.md — Wiki navigation elements.

Common Tasks

Updating the Sunset Schedule

The Gantt chart in Home.md (lines 33-117) shows when each version sunsets. When a new release is made:

1. Add a new Release X.Y.Z line in the Gantt chart (before the "Canonical Versions" section)
2. Set the release date and duration (365 days for beta versions)
3. Update the latest (unstable) line to point to the new release date
4. Update the v0 canonical version end date if the new release extends it

The pattern in the Gantt chart:

Release 0.X.0  :0.X.0, YYYY-MM-DD, 365d

Pre-Release Checklist

When preparing a release, the Releasing.md file contains the official checklist (lines 3-9):

• Verify README.md examples reflect the version
• Verify action.yml points to the correct version
• Ensure Docker image is built for linux/amd64 architecture
• Confirm canonical version (e.g., v0) tag points to the latest release
• Move the canonical tag on the action

Docker Build Commands

From Development.md:

Standard Linux/Intel build:

docker build -t jonasbn/github-action-spellcheck:latest .

Apple Silicon (M1) build:

docker build --platform linux/amd64 -t jonasbn/github-action-spellcheck:latest .

Check image architecture:

docker image inspect jonasbn/github-action-spellcheck:latest | grep -i architecture

Testing the Action

From Testing.md:

Local shell test:

INPUT_SOURCE_FILES="README.md CHANGELOG.md" INPUT_TASK_NAME=Markdown bash entrypoint.sh

Docker test:

docker run -e INPUT_SOURCE_FILES="README.md CHANGELOG.md" \
           -e INPUT_TASK_NAME=Markdown -it -v $PWD:/tmp \
           jonasbn/github-action-spellcheck:latest

Run GitHub Actions workflow:

gh workflow run "Spellcheck Action"

Release Process

The release process is automated via a Perl build script at scripts/build.pl. The workflow:

1. Takes a version argument
2. Validates Dockerfile, gh CLI, and action.yml exist
3. Confirms version in action.yml matches
4. Builds Docker images for linux/amd64
5. Pushes images to DockerHub
6. Updates the canonical v0 tag
7. Creates GitHub release

Manual tag movement (if needed):

# Remove local tag
git tag -d v0

# Remove remote tag  
git push origin --delete v0

# Create new tag and push
git tag -a v0
git push --tags

Versioning Strategy

• Exact versions (X.X.X): Available for 365 days, then sunset
• Canonical versions (vX): Available indefinitely (e.g., v0 always points to latest 0.X.X)
• Beta versions (0.X.X): All releases are currently beta
• Latest tag: Not stable; not recommended for production use

Key Files Outside This Wiki

This wiki documents an external action repository. Key files in the main repo that are referenced:

• Dockerfile — Action's container definition
• action.yml — GitHub Action metadata
• entrypoint.sh — Script tested in Testing.md
• scripts/build.pl — Perl build automation script
• Main repo: github.com/rojopolis/spellcheck-github-actions

Typical Workflow

1. Minor updates (fixing docs, correcting examples): Edit the relevant .md file and commit directly.
2. Sunset chart updates (when new releases are made): Update the Gantt chart in Home.md and the v0 canonical version date.
3. Release documentation: Add entries to Releasing.md if the process changes; update examples if action.yml structure changes.
4. Testing documentation: Update Testing.md if the entrypoint or testing procedures change.

Important Notes

• The latest Docker image tag is not stable — canonical versions (v0, v1, etc.) are recommended instead.
• Docker images are currently deleted manually when they sunset; consider automating this in the future.
• All interaction with DockerHub requires authentication with DOCKERHUB_ACCESS_TOKEN.
• Apple Silicon users must specify --platform linux/amd64 when building to ensure compatibility with GitHub Actions.