Development guidelines for the Glow project - a terminal-based markdown reader.
- Language: Go 1.24+
- Build:
go build - Test:
go test ./...ortask test - Lint:
golangci-lint runortask lint
- Use
gofumptfor formatting (stricter thangofmt) - Use
goimportsfor import organization - Tab indentation for Go files
- Follow existing patterns in the codebase
- Keep functions focused and modular
All work must start with an Issue. Do not implement features or fixes without a corresponding GitHub Issue.
- Check existing issues to avoid duplicates
- Use clear, descriptive titles
- Provide context: what, why, and acceptance criteria
- Apply appropriate labels (see Label Definitions below)
Only implement an Issue when it has the ready-for-pr label. This label signals:
- The issue has been triaged and accepted
- The approach has been discussed (if non-trivial)
- Someone can start implementation
| Label | Description |
|---|---|
type:bug |
Something isn't working correctly |
type:feature |
New functionality request |
type:docs |
Documentation improvements |
type:chore |
Maintenance, dependencies, CI |
| Label | Description |
|---|---|
status:triage |
Needs review and categorization |
status:accepted |
Issue is valid and will be addressed |
status:blocked |
Waiting on external dependency or decision |
status:wontfix |
Will not be addressed (with explanation) |
| Label | Description |
|---|---|
ready-for-pr |
Ready for implementation - PRs welcome |
| Label | Description |
|---|---|
priority:high |
Should be addressed soon |
priority:low |
Nice to have, no urgency |
type:bug - #d73a4a (red)
type:feature - #a2eeef (cyan)
type:docs - #0075ca (blue)
type:chore - #fef2c0 (yellow)
status:triage - #fbca04 (yellow)
status:accepted - #0e8a16 (green)
status:blocked - #b60205 (dark red)
status:wontfix - #ffffff (white)
ready-for-pr - #7057ff (purple)
priority:high - #ff6600 (orange)
priority:low - #c5def5 (light blue)
Run this task to create/update all labels in the repository:
task labels:syncTo have an AI agent review and re-label all open issues based on current conventions:
task labels:auditThis will output a report of suggested label changes. Review before applying.
- Find or create an Issue describing the bug
- Issue must have
type:bugandready-for-prlabels before starting work
- Reproduce the bug locally before making changes
- Read relevant code thoroughly to understand the root cause
- Check if there are existing tests covering the affected area
- Add a test case that reproduces the bug
- Place tests in the appropriate
*_test.gofile - For network-dependent tests, use
t.Skip()when network unavailable
- Make minimal, focused changes to fix the issue
- Avoid refactoring unrelated code in the same PR
- Follow existing code patterns and conventions
task lint # Check for linting issues
task test # Run all tests
go build # Ensure it compilesUse conventional commit format:
fix: brief description of the fix
Longer explanation if needed.
Fixes #123
- Find or create an Issue describing the feature
- Issue must have
type:featureandready-for-prlabels before starting work - For non-trivial features, discuss approach in the Issue first
- Review existing architecture in relevant packages:
main.go- CLI commands and source handlingui/- TUI components (pager, stash, styles)utils/- Helper utilities
- Identify which files need modification
- Consider cross-platform implications (see
*_windows.go,*_darwin.go)
- Start with core functionality
- Add UI components if needed (using Bubble Tea patterns)
- Follow existing patterns for:
- CLI flags: Use Cobra command structure in
main.go - Configuration: Use Viper patterns in
config_cmd.go - Styling: Use Lip Gloss patterns in
ui/styles.go
- CLI flags: Use Cobra command structure in
- Write unit tests for new functionality
- Test edge cases and error conditions
- Ensure tests pass locally before pushing
- Update README.md if adding user-facing features
- Add usage examples for new CLI flags
- Document configuration options if applicable
task lint # No new linting issues
task test # All tests pass
go build && ./glow # Manual testingUse conventional commit format:
feat: add new feature description
Explanation of what the feature does and why.
git checkout master
git pull origin master
git checkout -b feature/short-descriptionBranch naming conventions:
feature/- New featuresfix/- Bug fixesdocs/- Documentation changesrefactor/- Code refactoring
- Make focused, atomic commits
- Follow conventional commit format
- Keep commits logically grouped
task lint # Fix any linting issues
task test # Ensure all tests pass
go build # Verify it compilesgit push -u origin feature/short-description
gh pr create --title "feat: description" --body "## Summary
- What this PR does
## Test Plan
- How it was tested"If CI fails after pushing:
- Check the failing workflow in GitHub Actions
- Fix issues locally
- Push additional commits to the same branch
- CI will re-run automatically
- Address all reviewer comments
- Push fixes as new commits (don't force-push during review)
- Re-request review when ready
Ensure CI checks pass:
- build.yml - Build succeeds
- lint.yml - No new linting issues
- coverage.yml - Tests pass with coverage
- Code follows existing patterns and conventions
- No unnecessary complexity or over-engineering
- Functions are focused and appropriately sized
- Error handling is appropriate
- No hardcoded credentials or secrets
- User input is validated where applicable
- No obvious security vulnerabilities (OWASP top 10)
- New functionality has test coverage
- Edge cases are tested
- Tests are meaningful (not just for coverage)
- README updated for user-facing changes
- Code comments where logic isn't self-evident
- Commit messages follow conventional format
- Cross-platform considerations addressed
- No breaking changes to existing behavior (unless intentional)
- Be specific and actionable
- Explain the "why" behind suggestions
- Distinguish between blocking issues and nitpicks
- Approve when ready, request changes if blocking issues exist
The project uses extensive linting via .golangci.yml. Key enabled linters:
gosec- Security checksgoconst- Repeated strings that should be constantsmisspell- Spelling errorsrevive- Style and correctnesswrapcheck- Error wrappingunparam- Unused parameters
Run task lint before committing to catch issues early.
# Run all tests
task test
# Run with coverage
go test -race -covermode atomic -coverprofile=profile.cov ./...
# Run specific test
go test -run TestName ./...- Use table-driven tests for multiple cases
- Mark network-dependent tests with appropriate skip logic
- Keep tests focused and fast
Follow conventional commits:
type(scope): subject
body (optional)
footer (optional)
Types:
feat- New featurefix- Bug fixdocs- Documentation onlystyle- Formatting, no code changerefactor- Code change that neither fixes bug nor adds featuretest- Adding or updating testschore- Maintenance tasks
Examples:
feat: add support for GitLab URLs
fix: handle empty markdown files gracefully
chore(deps): bump golang.org/x/sys
/root/glow/
├── main.go # Entry point, CLI commands
├── ui/ # TUI components
│ ├── ui.go # Main UI model
│ ├── pager.go # Markdown viewport
│ ├── stash.go # File browser
│ └── styles.go # Styling definitions
├── utils/ # Helper utilities
├── Taskfile.yaml # Task runner config
├── .golangci.yml # Linter config
└── .github/workflows/ # CI/CD
Key libraries to be familiar with:
- cobra - CLI framework
- viper - Configuration
- bubbletea - TUI framework
- glamour - Markdown rendering
- lipgloss - Terminal styling
GitHub Actions runs on every PR:
- Build - Compiles for multiple platforms
- Lint - golangci-lint checks
- Coverage - Tests with race detector and coverage reporting
- Security - govulncheck, semgrep, ruleguard
All checks should pass before merging.
This fork uses date-based versioning instead of semantic versioning.
YYYY.MM.DD - Primary release for that date
YYYY.MM.DD.N - Additional releases on the same date (N = 1, 2, 3, ...)
Examples:
2025.12.30- First release on December 30, 20252025.12.30.1- Second release on the same day
-
Ensure master is ready
git checkout master git pull origin master task lint && task test && go build
-
Create a date-based tag
# Format: YYYY.MM.DD git tag 2025.12.30 git push origin 2025.12.30 -
CI/CD handles the rest
- Goreleaser builds static binaries for all platforms
- Creates GitHub Release with artifacts
- Generates checksums
The release includes static binaries for:
- Operating Systems: Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD
- Architectures: amd64 (x86_64), arm64
Each release includes:
- Binary archives (
.tar.gz,.zipfor Windows) - Shell completions (bash, zsh, fish)
- Man pages
- Checksums file
GitHub Releases only. No package managers (Homebrew, apt, etc.).
Users download binaries directly from:
https://github.com/hholst80/glow/releases
For same-day fixes:
git tag 2025.12.30.1
git push origin 2025.12.30.1