Skip to content

Commit 6a5f216

Browse files
CopilotBaseMax
Copilot
and
BaseMax
committed
Add quick reference guide and contributing guidelines
Co-authored-by: BaseMax <2658040+BaseMax@users.noreply.github.com>
1 parent cac508c commit 6a5f216

File tree

2 files changed

+293
-0
lines changed

2 files changed

+293
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Contributing to go-config-diff
2+
3+
Thank you for your interest in contributing to go-config-diff! This document provides guidelines and instructions for contributing.
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/go-config-diff.git`
9+
3. Create a feature branch: `git checkout -b feature/your-feature-name`
10+
4. Make your changes
11+
5. Run tests: `make test`
12+
6. Commit your changes: `git commit -am 'Add some feature'`
13+
7. Push to the branch: `git push origin feature/your-feature-name`
14+
8. Create a Pull Request
15+
16+
## Development Setup
17+
18+
### Prerequisites
19+
20+
- Go 1.24 or later
21+
- Make (optional, for using Makefile targets)
22+
23+
### Building
24+
25+
```bash
26+
make build
27+
```
28+
29+
### Running Tests
30+
31+
```bash
32+
make test
33+
```
34+
35+
### Running the Tool
36+
37+
```bash
38+
make run
39+
```
40+
41+
## Code Style
42+
43+
- Follow standard Go conventions
44+
- Use `gofmt` to format your code
45+
- Write meaningful commit messages
46+
- Add comments for complex logic
47+
- Keep functions focused and small
48+
49+
## Testing
50+
51+
- Write tests for new features
52+
- Ensure all tests pass before submitting PR
53+
- Add test cases for edge cases
54+
- Update existing tests if behavior changes
55+
56+
### Test Structure
57+
58+
```
59+
pkg/
60+
ast/
61+
ast.go
62+
ast_test.go # Tests for AST functionality
63+
parser/
64+
parser.go
65+
parser_test.go # Tests for parsers
66+
diff/
67+
diff.go
68+
diff_test.go # Tests for diff logic
69+
```
70+
71+
## Adding a New Format
72+
73+
To add support for a new configuration format:
74+
75+
1. Add the format constant to `pkg/parser/parser.go`:
76+
```go
77+
const FormatXML Format = "xml"
78+
```
79+
80+
2. Update `DetectFormat()` to recognize the file extension
81+
82+
3. Implement a parser function:
83+
```go
84+
func parseXML(r io.Reader) (interface{}, error) {
85+
// Parse XML and return as interface{}
86+
}
87+
```
88+
89+
4. Add the case to `ParseReader()` switch statement
90+
91+
5. Add tests in `pkg/parser/parser_test.go`
92+
93+
6. Add example files in `examples/` directory
94+
95+
7. Update documentation
96+
97+
## Pull Request Guidelines
98+
99+
- **Title**: Use a clear, descriptive title
100+
- **Description**: Explain what changes you made and why
101+
- **Tests**: Include tests for new functionality
102+
- **Documentation**: Update README or other docs if needed
103+
- **One feature per PR**: Keep PRs focused on a single feature or fix
104+
105+
## Reporting Issues
106+
107+
When reporting issues, please include:
108+
109+
- Go version: `go version`
110+
- Operating system and version
111+
- Clear description of the problem
112+
- Steps to reproduce
113+
- Expected vs actual behavior
114+
- Error messages or logs
115+
- Sample configuration files (if applicable)
116+
117+
## Feature Requests
118+
119+
We welcome feature requests! Please:
120+
121+
- Check if the feature already exists
122+
- Search existing issues for similar requests
123+
- Provide a clear use case
124+
- Explain why the feature would be valuable
125+
126+
## Code Review Process
127+
128+
1. All PRs require review before merging
129+
2. Address review comments
130+
3. Keep the discussion constructive and professional
131+
4. PRs may be updated by maintainers to fix minor issues
132+
133+
## Project Structure
134+
135+
```
136+
go-config-diff/
137+
├── cmd/
138+
│ └── go-config-diff/ # CLI entry point
139+
├── pkg/
140+
│ ├── ast/ # Abstract Syntax Tree
141+
│ ├── parser/ # Format parsers
142+
│ ├── diff/ # Comparison logic
143+
│ └── output/ # Output formatters
144+
├── examples/ # Example config files
145+
├── Makefile # Build automation
146+
└── README.md # Documentation
147+
```
148+
149+
## Areas for Contribution
150+
151+
- **New format support**: Add XML, HOCON, or other formats
152+
- **Output formats**: Add more output options (HTML, Markdown, etc.)
153+
- **Performance**: Optimize comparison for large files
154+
- **Documentation**: Improve examples and guides
155+
- **Tests**: Add more test coverage
156+
- **Bug fixes**: Fix reported issues
157+
158+
## Questions?
159+
160+
Feel free to open an issue with your question or reach out to the maintainers.
161+
162+
## License
163+
164+
By contributing, you agree that your contributions will be licensed under the GPL-3.0 License.
165+
166+
Thank you for contributing to go-config-diff! 🎉

‎QUICKREF.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Quick Reference Guide
2+
3+
## Installation
4+
5+
```bash
6+
go install github.com/BaseMax/go-config-diff/cmd/go-config-diff@latest
7+
```
8+
9+
## Basic Commands
10+
11+
```bash
12+
# Compare two config files
13+
go-config-diff config1.yaml config2.yaml
14+
15+
# Use different output format
16+
go-config-diff -format=json config1.json config2.json
17+
go-config-diff -format=plain config1.toml config2.toml
18+
19+
# Show summary of changes
20+
go-config-diff -summary config1.ini config2.ini
21+
22+
# Show version
23+
go-config-diff -version
24+
25+
# Show help
26+
go-config-diff -help
27+
```
28+
29+
## Output Symbols
30+
31+
- `+` Green: Added field or value
32+
- `-` Red: Removed field or value
33+
- `~` Yellow: Modified field or value
34+
35+
## Exit Codes
36+
37+
- `0`: No differences found
38+
- `1`: Differences found or error occurred
39+
40+
## Supported Formats
41+
42+
- YAML (`.yaml`, `.yml`)
43+
- JSON (`.json`)
44+
- TOML (`.toml`)
45+
- INI (`.ini`, `.conf`)
46+
47+
## Use Cases
48+
49+
### CI/CD Pipeline
50+
```bash
51+
# Exit with error if configs differ
52+
go-config-diff prod-config.yaml staging-config.yaml
53+
```
54+
55+
### Generate Machine-Readable Report
56+
```bash
57+
# Output JSON for further processing
58+
go-config-diff -format=json old.json new.json > diff-report.json
59+
```
60+
61+
### Quick Visual Check
62+
```bash
63+
# Colored output with summary
64+
go-config-diff -summary app-v1.yaml app-v2.yaml
65+
```
66+
67+
## Features
68+
69+
✅ Semantic comparison (not line-by-line)
70+
✅ Ignores key ordering in objects/maps
71+
✅ Deep nested structure comparison
72+
✅ Type-aware comparison
73+
✅ Multiple output formats
74+
✅ Colored terminal output
75+
✅ Path tracking for changes
76+
✅ Summary statistics
77+
78+
## Common Patterns
79+
80+
### Compare across formats
81+
```bash
82+
# Even different formats are compared semantically
83+
go-config-diff config.yaml config.json
84+
```
85+
86+
### Integration with Git
87+
```bash
88+
# Compare config between branches
89+
git show main:config.yaml > /tmp/old.yaml
90+
git show feature:config.yaml > /tmp/new.yaml
91+
go-config-diff /tmp/old.yaml /tmp/new.yaml
92+
```
93+
94+
### Automation
95+
```bash
96+
# Use in scripts
97+
if go-config-diff base.yaml custom.yaml; then
98+
echo "Configs are identical"
99+
else
100+
echo "Configs differ"
101+
fi
102+
```
103+
104+
## Building from Source
105+
106+
```bash
107+
git clone https://github.com/BaseMax/go-config-diff.git
108+
cd go-config-diff
109+
make build
110+
./go-config-diff -version
111+
```
112+
113+
## Development
114+
115+
```bash
116+
# Run tests
117+
make test
118+
119+
# Build binary
120+
make build
121+
122+
# Run with examples
123+
make run
124+
125+
# Clean artifacts
126+
make clean
127+
```

0 commit comments

Comments
 (0)