johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Polish for open-source release

Browse Source 
Major improvements to code quality, documentation, and CI:

Code Quality:
- Add golangci-lint configuration with 13 linters
- Fix unchecked error returns in export/import/init
- Refactor duplicate scanIssues code
- Add package comments for all packages
- Add const block comments for exported constants
- Configure errcheck to allow idiomatic defer patterns

Documentation:
- Add comprehensive CONTRIBUTING.md with setup, testing, and workflow
- Fix QUICKSTART.md binary name references (beads → bd)
- Correct default database path documentation

CI/CD:
- Add GitHub Actions workflow for tests and linting
- Enable race detection and coverage reporting
- Automated quality checks on all PRs

All tests passing. Lint issues reduced from 117 to 103 (remaining are
idiomatic patterns and test code). Ready for open-source release.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-10-12 09:41:29 -07:00
parent 9a768ba4a3
commit 87ed7c8793
12 changed files with 430 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
.github/workflows/ci.yml vendored Normal file
View File

@@ -0,0 +1,49 @@
name: CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
test:
name: Test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.25'
- name: Build
run: go build -v ./cmd/bd
- name: Test
run: go test -v -race -coverprofile=coverage.out ./...
- name: Upload coverage
uses: codecov/codecov-action@v4
if: success()
with:
file: ./coverage.out
fail_ci_if_error: false
lint:
name: Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: '1.25'
- name: golangci-lint
uses: golangci/golangci-lint-action@v6
with:
version: latest
args: --timeout=5m

75
.golangci.yml Normal file
View File

@@ -0,0 +1,75 @@
# golangci-lint configuration for beads
# See https://golangci-lint.run/usage/configuration/
version: 2
run:
timeout: 5m
tests: true
linters:
enable:
# Core linters (always available)
- errcheck # Check for unchecked errors
- govet # Go vet
- ineffassign # Detect ineffectual assignments
- staticcheck # Static analysis
- unused # Find unused code
# Additional linters
- revive # Fast, configurable, extensible linter
- misspell # Fix commonly misspelled English words
- unconvert # Remove unnecessary type conversions
- unparam # Find unused function parameters
- goconst # Find repeated strings that could be constants
- gocyclo # Check cyclomatic complexity
- dupl # Find duplicated code
- gosec # Security-focused linter
linters-settings:
errcheck:
check-type-assertions: true
check-blank: false
exclude-functions:
- (*database/sql.DB).Close
- (*database/sql.Rows).Close
- (*database/sql.Tx).Rollback
gocyclo:
min-complexity: 15
goconst:
min-len: 3
min-occurrences: 3
dupl:
threshold: 100
misspell:
locale: US
revive:
rules:
- name: var-naming
- name: exported
issues:
max-issues-per-linter: 0
max-same-issues: 0
# Exclude some linters from running on tests
exclude-rules:
- path: _test\.go
linters:
- dupl
- gosec
- goconst
- errcheck # Defer/cleanup in tests is often acceptable
# Cobra command handlers often don't use cmd/args parameters
- text: "unused-parameter.*cmd.*cobra\\.Command"
linters:
- revive
- text: "unused-parameter.*args.*string"
linters:
- revive

260
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,260 @@
# Contributing to bd
Thank you for your interest in contributing to bd! This document provides guidelines and instructions for contributing.
## Development Setup
### Prerequisites
- Go 1.25 or later
- Git
- (Optional) golangci-lint for local linting
### Getting Started
```bash
# Clone the repository
git clone https://github.com/steveyegge/beads
cd beads
# Build the project
go build -o bd ./cmd/bd
# Run tests
go test ./...
# Run with race detection
go test -race ./...
# Build and install locally
go install ./cmd/bd
```
## Project Structure
```
beads/
├── cmd/bd/ # CLI entry point and commands
├── internal/
│ ├── types/ # Core data types (Issue, Dependency, etc.)
│ └── storage/ # Storage interface and implementations
│ └── sqlite/ # SQLite backend
├── .golangci.yml # Linter configuration
└── .github/workflows/ # CI/CD pipelines
```
## Running Tests
```bash
# Run all tests
go test ./...
# Run tests with coverage
go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
# Run specific package tests
go test ./internal/storage/sqlite -v
# Run tests with race detection
go test -race ./...
```
## Code Style
We follow standard Go conventions:
- Use `gofmt` to format your code (runs automatically in most editors)
- Follow the [Effective Go](https://golang.org/doc/effective_go) guidelines
- Keep functions small and focused
- Write clear, descriptive variable names
- Add comments for exported functions and types
### Linting
We use golangci-lint for code quality checks:
```bash
# Install golangci-lint
brew install golangci-lint # macOS
# or
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
# Run linter
golangci-lint run ./...
```
CI will automatically run linting on all pull requests.
## Making Changes
### Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run tests and linter locally
6. Commit your changes with clear messages
7. Push to your fork
8. Open a pull request
### Commit Messages
Write clear, concise commit messages:
```
Add cycle detection for dependency graphs
- Implement recursive CTE-based cycle detection
- Add tests for simple and complex cycles
- Update documentation with examples
```
### Pull Requests
- Keep PRs focused on a single feature or fix
- Include tests for new functionality
- Update documentation as needed
- Ensure CI passes before requesting review
- Respond to review feedback promptly
## Testing Guidelines
- Write table-driven tests when testing multiple scenarios
- Use descriptive test names that explain what is being tested
- Clean up resources (database files, etc.) in test teardown
- Use `t.Run()` for subtests to organize related test cases
Example:
```go
func TestIssueValidation(t *testing.T) {
tests := []struct {
name string
issue *types.Issue
wantErr bool
}{
{
name: "valid issue",
issue: &types.Issue{Title: "Test", Status: types.StatusOpen, Priority: 2},
wantErr: false,
},
{
name: "missing title",
issue: &types.Issue{Status: types.StatusOpen, Priority: 2},
wantErr: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := tt.issue.Validate()
if (err != nil) != tt.wantErr {
t.Errorf("Validate() error = %v, wantErr %v", err, tt.wantErr)
}
})
}
}
```
## Documentation
- Update README.md for user-facing changes
- Update relevant .md files in the project root
- Add inline code comments for complex logic
- Include examples in documentation
## Feature Requests and Bug Reports
### Reporting Bugs
Include in your bug report:
- Steps to reproduce
- Expected behavior
- Actual behavior
- Version of bd (`bd version` if implemented)
- Operating system and Go version
### Feature Requests
When proposing new features:
- Explain the use case
- Describe the proposed solution
- Consider backwards compatibility
- Discuss alternatives you've considered
## Code Review Process
All contributions go through code review:
1. Automated checks (tests, linting) must pass
2. At least one maintainer approval required
3. Address review feedback
4. Maintainer will merge when ready
## Development Tips
### Testing Locally
```bash
# Build and test your changes quickly
go build -o bd ./cmd/bd && ./bd init --prefix test
# Test specific functionality
./bd create "Test issue" -p 1 -t bug
./bd dep add test-2 test-1
./bd ready
```
### Database Inspection
```bash
# Inspect the SQLite database directly
sqlite3 .beads/test.db
# Useful queries
SELECT * FROM issues;
SELECT * FROM dependencies;
SELECT * FROM events WHERE issue_id = 'test-1';
```
### Debugging
Use Go's built-in debugging tools:
```bash
# Run with verbose logging
go run ./cmd/bd -v create "Test"
# Use delve for debugging
dlv debug ./cmd/bd -- create "Test issue"
```
## Release Process
(For maintainers)
1. Update version in code
2. Update CHANGELOG.md
3. Tag release: `git tag v0.x.0`
4. Push tag: `git push origin v0.x.0`
5. GitHub Actions will build and publish
## Questions?
- Check existing [issues](https://github.com/steveyegge/beads/issues)
- Open a new issue for questions
- Review [README.md](README.md) and other documentation
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
## Code of Conduct
Be respectful and professional in all interactions. We're here to build something great together.
---
Thank you for contributing to bd! 🎉

42
QUICKSTART.md
View File

@@ -6,33 +6,33 @@ Get up and running with Beads in 2 minutes.
```bash
cd ~/src/beads
go build -o beads ./cmd/beads
./beads --help
go build -o bd ./cmd/bd
./bd --help
```
## Your First Issues
```bash
# Create a few issues
./beads create "Set up database" -p 1 -t task
./beads create "Create API" -p 2 -t feature
./beads create "Add authentication" -p 2 -t feature
./bd create "Set up database" -p 1 -t task
./bd create "Create API" -p 2 -t feature
./bd create "Add authentication" -p 2 -t feature
# List them
./beads list
./bd list
```
## Add Dependencies
```bash
# API depends on database
./beads dep add bd-2 bd-1
./bd dep add bd-2 bd-1
# Auth depends on API
./beads dep add bd-3 bd-2
./bd dep add bd-3 bd-2
# View the tree
./beads dep tree bd-3
./bd dep tree bd-3
```
Output:
@@ -47,7 +47,7 @@ Output:
## Find Ready Work
```bash
./beads ready
./bd ready
```
Output:
@@ -63,13 +63,13 @@ Only bd-1 is ready because bd-2 and bd-3 are blocked!
```bash
# Start working on bd-1
./beads update bd-1 --status in_progress
./bd update bd-1 --status in_progress
# Complete it
./beads close bd-1 --reason "Database setup complete"
./bd close bd-1 --reason "Database setup complete"
# Check ready work again
./beads ready
./bd ready
```
Now bd-2 is ready! 🎉
@@ -78,27 +78,27 @@ Now bd-2 is ready! 🎉
```bash
# See blocked issues
./beads blocked
./bd blocked
# View statistics
./beads stats
./bd stats
```
## Database Location
By default: `~/.beads/beads.db`
By default: `~/.beads/default.db`
You can use project-specific databases:
```bash
./beads --db ./my-project.db create "Task"
./bd --db ./my-project.db create "Task"
```
## Next Steps
- Add labels: `./beads create "Task" -l "backend,urgent"`
- Filter ready work: `./beads ready --priority 1`
- Search issues: `./beads list --status open`
- Detect cycles: `./beads dep cycles`
- Add labels: `./bd create "Task" -l "backend,urgent"`
- Filter ready work: `./bd ready --priority 1`
- Search issues: `./bd list --status open`
- Detect cycles: `./bd dep cycles`
See [README.md](README.md) for full documentation.

6
cmd/bd/export.go
View File

@@ -56,7 +56,11 @@ Output to stdout by default, or use -o flag for file output.`,
fmt.Fprintf(os.Stderr, "Error creating output file: %v\n", err)
os.Exit(1)
}
defer f.Close()
defer func() {
if err := f.Close(); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to close output file: %v\n", err)
}
}()
out = f
}

6
cmd/bd/import.go
View File

@@ -34,7 +34,11 @@ Behavior:
fmt.Fprintf(os.Stderr, "Error opening input file: %v\n", err)
os.Exit(1)
}
defer f.Close()
defer func() {
if err := f.Close(); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to close input file: %v\n", err)
}
}()
in = f
}

6
cmd/bd/init.go
View File

@@ -47,11 +47,13 @@ and database file. Optionally specify a custom issue prefix.`,
ctx := context.Background()
if err := store.SetConfig(ctx, "issue_prefix", prefix); err != nil {
fmt.Fprintf(os.Stderr, "Error: failed to set issue prefix: %v\n", err)
store.Close()
_ = store.Close()
os.Exit(1)
}
store.Close()
if err := store.Close(); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to close database: %v\n", err)
}
green := color.New(color.FgGreen).SprintFunc()
cyan := color.New(color.FgCyan).SprintFunc()

2
cmd/bd/main.go
View File

@@ -64,7 +64,7 @@ var rootCmd = &cobra.Command{
},
PersistentPostRun: func(cmd *cobra.Command, args []string) {
if store != nil {
store.Close()
_ = store.Close()
}
},
}

1
internal/storage/sqlite/dependencies.go
View File

@@ -1,3 +1,4 @@
// Package sqlite implements dependency management for the SQLite storage backend.
package sqlite
import (

35
internal/storage/sqlite/sqlite.go
View File

@@ -1,3 +1,4 @@
// Package sqlite implements the storage interface using SQLite.
package sqlite
import (
@@ -11,6 +12,7 @@ import (
"sync"
"time"
// Import SQLite driver
_ "github.com/mattn/go-sqlite3"
"github.com/steveyegge/beads/internal/types"
)
@@ -404,38 +406,7 @@ func (s *SQLiteStorage) SearchIssues(ctx context.Context, query string, filter t
}
defer rows.Close()
var issues []*types.Issue
for rows.Next() {
var issue types.Issue
var closedAt sql.NullTime
var estimatedMinutes sql.NullInt64
var assignee sql.NullString
err := rows.Scan(
&issue.ID, &issue.Title, &issue.Description, &issue.Design,
&issue.AcceptanceCriteria, &issue.Notes, &issue.Status,
&issue.Priority, &issue.IssueType, &assignee, &estimatedMinutes,
&issue.CreatedAt, &issue.UpdatedAt, &closedAt,
)
if err != nil {
return nil, fmt.Errorf("failed to scan issue: %w", err)
}
if closedAt.Valid {
issue.ClosedAt = &closedAt.Time
}
if estimatedMinutes.Valid {
mins := int(estimatedMinutes.Int64)
issue.EstimatedMinutes = &mins
}
if assignee.Valid {
issue.Assignee = assignee.String
}
issues = append(issues, &issue)
}
return issues, nil
return scanIssues(rows)
}
// SetConfig sets a configuration value

1
internal/storage/storage.go
View File

@@ -1,3 +1,4 @@
// Package storage defines the interface for issue storage backends.
package storage
import (

5
internal/types/types.go
View File

@@ -1,3 +1,4 @@
// Package types defines core data structures for the bd issue tracker.
package types
import (
@@ -49,6 +50,7 @@ func (i *Issue) Validate() error {
// Status represents the current state of an issue
type Status string
// Issue status constants
const (
StatusOpen Status = "open"
StatusInProgress Status = "in_progress"
@@ -68,6 +70,7 @@ func (s Status) IsValid() bool {
// IssueType categorizes the kind of work
type IssueType string
// Issue type constants
const (
TypeBug IssueType = "bug"
TypeFeature IssueType = "feature"
@@ -97,6 +100,7 @@ type Dependency struct {
// DependencyType categorizes the relationship
type DependencyType string
// Dependency type constants
const (
DepBlocks DependencyType = "blocks"
DepRelated DependencyType = "related"
@@ -134,6 +138,7 @@ type Event struct {
// EventType categorizes audit trail events
type EventType string
// Event type constants for audit trail
const (
EventCreated EventType = "created"
EventUpdated EventType = "updated"