Skip to content

Commit de62ed4

Browse files
CopilotCopilot
authored
Add comprehensive GitHub Copilot instructions for go-configparser development (#24)
Add comprehensive GitHub Copilot instructions for go-configparser
1 parent a679eef commit de62ed4

File tree

1 file changed

+190
-0
lines changed

1 file changed

+190
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# go-configparser Development Instructions
2+
3+
**ALWAYS follow these instructions first and only fallback to additional search and context gathering if the information here is incomplete or found to be in error.**
4+
5+
go-configparser is a Go library that implements a Python ConfigParser-compatible configuration file parser with support for interpolation, custom options, and all major ConfigParser features.
6+
7+
## Quick Start & Validation
8+
9+
Bootstrap and validate the repository with these commands:
10+
- `go version` -- ensure Go 1.21+ is installed
11+
- `go build -v ./...` -- builds in ~7 seconds, NEVER CANCEL
12+
- `go test -v ./...` -- runs in ~5 seconds with 93.1% test coverage, NEVER CANCEL
13+
- `go test -cover ./...` -- shows test coverage statistics
14+
15+
## Essential Development Commands
16+
17+
### Building
18+
- `go build -v ./...` -- build all packages (7 seconds)
19+
- `go build` -- build current package only
20+
21+
### Testing
22+
- `go test -v ./...` -- run all tests with verbose output (5 seconds)
23+
- `go test -cover ./...` -- run tests with coverage report
24+
- `go test ./chainmap` -- run tests for chainmap subpackage only
25+
- `go test -check.f TestSpecificFunction` -- run specific test (uses check framework)
26+
27+
### Code Quality
28+
- `go vet ./...` -- static analysis, runs instantly
29+
- `gofmt -l .` -- check code formatting, runs instantly
30+
- `go mod tidy` -- clean up module dependencies
31+
- `~/go/bin/golangci-lint run` -- comprehensive linting (install first with: `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`, takes ~2 minutes to install)
32+
33+
### CRITICAL: Always run before committing
34+
- `go build -v ./...` -- ensure code builds
35+
- `go test -v ./...` -- ensure tests pass
36+
- `go vet ./...` -- static analysis
37+
- `gofmt -l .` -- verify formatting (should return no output)
38+
39+
## Validation Scenarios
40+
41+
ALWAYS test functionality after making changes by running this validation scenario:
42+
43+
1. Create a test program to validate core functionality:
44+
```go
45+
package main
46+
47+
import (
48+
"fmt"
49+
"log"
50+
"github.com/bigkevmcd/go-configparser"
51+
)
52+
53+
func main() {
54+
// Test parsing the example configuration file
55+
p, err := configparser.NewConfigParserFromFile("testdata/example.cfg")
56+
if err != nil {
57+
log.Fatal(err)
58+
}
59+
60+
// Test basic functionality
61+
sections := p.Sections()
62+
fmt.Printf("Sections: %v\n", sections)
63+
64+
// Test getting a value
65+
value, err := p.Get("follower", "FrobTimeout")
66+
if err != nil {
67+
log.Fatal(err)
68+
}
69+
fmt.Printf("FrobTimeout: %s\n", value)
70+
71+
// Test interpolation
72+
interpolated, err := p.GetInterpolated("follower", "builder_command")
73+
if err != nil {
74+
log.Fatal(err)
75+
}
76+
fmt.Printf("Interpolated: %s\n", interpolated)
77+
78+
fmt.Println("✓ Working correctly!")
79+
}
80+
```
81+
82+
2. Save this as `/tmp/test_validation.go` and run: `go run /tmp/test_validation.go`
83+
3. Expected output should show sections, values, and interpolated results
84+
4. ALWAYS verify this works after making changes to core parsing logic
85+
86+
## Codebase Navigation
87+
88+
### Key Files & Their Purpose
89+
- `configparser.go` -- Core ConfigParser struct and parsing logic
90+
- `methods.go` -- Main API methods (Get, Set, Sections, etc.)
91+
- `interpolation.go` -- Value interpolation handling (%(var)s syntax)
92+
- `options.go` -- Configuration options and customization
93+
- `section.go` -- Section management and operations
94+
- `chainmap/chainmap.go` -- ChainMap implementation for interpolation lookups
95+
96+
### Test Files
97+
- `configparser_test.go` -- Core parsing tests
98+
- `methods_test.go` -- API method tests
99+
- `interpolation_test.go` -- Interpolation tests
100+
- `options_test.go` -- Options and customization tests
101+
- `chainmap/chainmap_test.go` -- ChainMap tests
102+
103+
### Example & Test Data
104+
- `testdata/example.cfg` -- Example configuration file with interpolation
105+
- Uses standard INI format with sections, key=value pairs, and %(var)s interpolation
106+
107+
## Common Development Tasks
108+
109+
### Adding New Features
110+
1. ALWAYS add tests first in the appropriate `*_test.go` file
111+
2. Follow the existing test patterns using `gopkg.in/check.v1`
112+
3. Implement the feature in the corresponding main file
113+
4. Run validation: `go test -v ./... && go build -v ./...`
114+
5. Test manually with validation scenario above
115+
116+
### Debugging Configuration Parsing
117+
- Use `testdata/example.cfg` as a reference for valid syntax
118+
- The library supports: sections `[name]`, key=value pairs, comments with `#` or `;`, interpolation with `%(var)s`
119+
- Check `interpolation.go` for interpolation logic
120+
- Check `options.go` for customization options
121+
122+
### Working with Interpolation
123+
- Interpolation uses `%(variable_name)s` syntax
124+
- Variables resolved from DEFAULT section and current section
125+
- ChainMap in `chainmap/` package handles lookup chain
126+
- Test interpolation changes with example config file
127+
128+
## Project Structure
129+
130+
```
131+
.
132+
├── .github/workflows/go.yml # CI pipeline (Go 1.22, build + test)
133+
├── README.md # Project documentation
134+
├── go.mod # Go module definition (requires Go 1.21+)
135+
├── configparser.go # Main parser implementation
136+
├── methods.go # Core API methods
137+
├── interpolation.go # Interpolation logic
138+
├── options.go # Configuration options
139+
├── section.go # Section management
140+
├── chainmap/ # ChainMap package for interpolation
141+
│ ├── chainmap.go
142+
│ └── chainmap_test.go
143+
├── testdata/
144+
│ └── example.cfg # Example configuration file
145+
└── *_test.go # Test files
146+
```
147+
148+
## CI/CD Information
149+
150+
The GitHub Actions workflow (`.github/workflows/go.yml`):
151+
- Runs on: Ubuntu latest
152+
- Go version: 1.22 (but works with 1.21+)
153+
- Steps: Checkout → Setup Go → Build → Test
154+
- Build command: `go build -v ./...`
155+
- Test command: `go test -v ./...`
156+
157+
ALWAYS ensure your changes pass both build and test steps locally before pushing.
158+
159+
## Dependencies
160+
161+
- Main dependency: `gopkg.in/check.v1` for testing
162+
- No external runtime dependencies
163+
- Standard library only for core functionality
164+
- Uses Go modules for dependency management
165+
166+
## Performance Notes
167+
168+
- Build time: ~7 seconds (very fast)
169+
- Test time: ~5 seconds (very fast)
170+
- golangci-lint install: ~2 minutes (one-time setup)
171+
- golangci-lint run: ~few seconds
172+
173+
## Troubleshooting
174+
175+
### Build Issues
176+
- Ensure Go 1.21+ is installed: `go version`
177+
- Clean module cache: `go clean -modcache`
178+
- Verify dependencies: `go mod download`
179+
180+
### Test Issues
181+
- Run specific test: `go test -run TestName`
182+
- Check test coverage: `go test -cover ./...`
183+
- Validate with example: `go run /tmp/test_validation.go`
184+
185+
### Linting Issues
186+
- Minor linting issues exist in test files (unchecked errors)
187+
- Main code passes all linters
188+
- Install linter first: `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`
189+
190+
Remember: This is a library, not an application. Focus on API correctness, test coverage, and compatibility with Python ConfigParser behavior.

0 commit comments

Comments
 (0)