Skip to content

Add self-documenting make help target and reusable Makefile skill - #1

Merged
vlantonov merged 2 commits into
mainfrom
add_makefile_help
Aug 22, 2026
Merged

vlantonov merged 2 commits into
mainfrom
add_makefile_help

Conversation

@vlantonov

Copy link
Copy Markdown
Owner

Summary

Developers cloning the project had no discoverable way to learn what make targets were available without reading the Makefile directly. This PR adds a help target that auto-generates a target listing from inline ## description comments, making the project more approachable for new contributors and portfolio viewers. It also packages the pattern as a reusable Copilot skill so the same workflow can be applied to other Makefiles in one command.

Motivation / Context

  • Addresses the onboarding usability gap: bare make previously defaulted to build with no usage guidance.
  • No linked issue; change is self-contained and additive.
  • Known limitation: the grep pattern matches single-colon rules only; double-colon rules (target:: ## …) would require a pattern adjustment.

What Changed

Build tooling (Makefile)

  • Added help target with grep/awk recipe that prints all ## description-annotated targets in colour-coded, aligned columns.
  • Set .DEFAULT_GOAL := help so bare make prints usage instead of building.
  • Added ## description inline comments to all five existing targets (build, test, vet, clean, run).
  • Added help to the .PHONY declaration.

Developer tooling (makefile-help)

  • New SKILL.md: VS Code Copilot on-demand skill (/makefile-help) with a 4-step procedure — read, annotate, insert, validate.
  • New assets/help-target.mk: reusable drop-in Makefile snippet bundled with the skill.

How It Was Tested / Verified

  • make help — all 6 targets listed with correct descriptions (output captured below).
  • make build — compiles cleanly, no new warnings.
  • make test — all 5 package test suites pass with -race flag (config, grid, robot, simulation, tui).
  • make vet — no issues reported.
  • No existing recipe lines were modified; diff confirms recipe preservation.

Screenshots / Output Samples

Usage:
  make <target>

Targets:
  build                Compile the binary
  clean                Remove compiled binary
  help                 Show this help message
  run                  Run the robot demo
  test                 Run all tests with race detector
  vet                  Run go vet on all packages

Checklist

  • Builds cleanly with the project's standard build configuration
  • Tests pass locally
  • Documentation / README updated if behavior or usage changed — make help is self-documenting; README make section can optionally reference make help in a follow-up
  • No new warnings introduced by the configured toolchain/checks

…targets

Why:
- Provides a reusable on-demand workflow for annotating Makefile targets
  and inserting a self-documenting `make help` target

What changed:
- .github/skills/makefile-help/SKILL.md: new skill with 4-step procedure
  (read, annotate, insert help target, validate)
- .github/skills/makefile-help/assets/help-target.mk: Makefile snippet
  with .DEFAULT_GOAL, .PHONY, and grep/awk help recipe

Compatibility:
- Backward-compatible because only new files are added; no existing
  Makefile, source, or configuration is modified

Validation:
- Frontmatter YAML is valid; asset is syntactically correct GNU make;
  skill appears as /makefile-help slash command in VS Code Copilot
Why:
- Developers had no way to discover available make targets without
  reading the Makefile directly

What changed:
- Makefile: added help target with grep/awk recipe that prints all
  targets annotated with ## comments
- Makefile: set .DEFAULT_GOAL := help so bare `make` shows usage
- Makefile: added ## inline descriptions to build, test, vet, clean, run
- Makefile: added help to .PHONY declaration

Compatibility:
- Backward-compatible because no Go source, public API, or compiled
  binary behavior is changed; all existing targets are preserved unchanged

Validation:
- `make help` confirmed; all 6 targets listed with correct descriptions
- `make build`, `make test`, `make vet`, `make run`, `make clean`
  recipes are unmodified
@vlantonov
vlantonov merged commit 7731176 into main Aug 22, 2026
1 check passed
@vlantonov
vlantonov deleted the add_makefile_help branch August 22, 2026 09:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants