Skip to content

Commit 49d82c4

Browse files
miton18miton18
committed
init
0 parents  commit 49d82c4

File tree

7 files changed

+841
-0
lines changed

7 files changed

+841
-0
lines changed

‎.github/CI.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Continuous Integration
2+
3+
This repository uses GitHub Actions for continuous integration and testing.
4+
5+
## Workflows
6+
7+
### Test Workflow (`.github/workflows/test.yml`)
8+
9+
Runs on:
10+
- Pull requests to `main` or `master`
11+
- Pushes to `main` or `master`
12+
13+
#### Jobs
14+
15+
**1. Test**
16+
- Runs on: `ubuntu-latest`
17+
- Go version: `1.24`
18+
- Steps:
19+
- Checkout code
20+
- Set up Go with caching
21+
- Download and verify dependencies
22+
- Run tests with race detection
23+
- Generate coverage report
24+
- Upload coverage to Codecov (optional)
25+
26+
**2. Lint**
27+
- Runs on: `ubuntu-latest`
28+
- Go version: `1.24`
29+
- Steps:
30+
- Checkout code
31+
- Set up Go with caching
32+
- Run `golangci-lint` with 5m timeout
33+
34+
**3. Build**
35+
- Runs on: `ubuntu-latest`
36+
- Go version: `1.24`
37+
- Steps:
38+
- Checkout code
39+
- Set up Go with caching
40+
- Build all packages
41+
42+
## Test Environment
43+
44+
### Docker Requirements
45+
The integration tests use [Testcontainers](https://golang.testcontainers.org/) to spin up a Quickwit instance in Docker.
46+
47+
GitHub Actions runners have Docker pre-installed, so tests run automatically in CI.
48+
49+
### Test Configuration
50+
- Timeout: 10 minutes
51+
- Race detection: Enabled
52+
- Coverage: Enabled
53+
- Container logs: Disabled in CI (set `CONTAINER_LOG=false`)
54+
55+
## Linting
56+
57+
The project uses `golangci-lint` with the following enabled linters:
58+
- `gofmt` - Format checking
59+
- `govet` - Go vet
60+
- `errcheck` - Unchecked errors
61+
- `staticcheck` - Static analysis
62+
- `ineffassign` - Ineffectual assignments
63+
- `unused` - Unused code
64+
- `gosimple` - Simplification suggestions
65+
- `misspell` - Spelling mistakes
66+
- `unconvert` - Unnecessary conversions
67+
- `unparam` - Unused function parameters
68+
- `exportloopref` - Loop variable references
69+
70+
Configuration: `.golangci.yml`
71+
72+
## Dependabot
73+
74+
Dependabot is configured to automatically:
75+
- Update Go module dependencies weekly
76+
- Update GitHub Actions versions weekly
77+
- Create PRs with labels: `dependencies`, `go`, `github-actions`
78+
79+
Configuration: `.github/dependabot.yml`
80+
81+
## Status Badges
82+
83+
The following badges are available in the README:
84+
85+
- **Tests**: ![Tests](https://github.com/miton18/quickwit-go/actions/workflows/test.yml/badge.svg)
86+
- **Go Report Card**: [![Go Report Card](https://goreportcard.com/badge/github.com/miton18/quickwit-go)](https://goreportcard.com/report/github.com/miton18/quickwit-go)
87+
- **GoDoc**: [![GoDoc](https://godoc.org/github.com/miton18/quickwit-go?status.svg)](https://godoc.org/github.com/miton18/quickwit-go)
88+
89+
## Local Development
90+
91+
### Running Tests Locally
92+
```bash
93+
# Run all tests
94+
go test -v ./...
95+
96+
# Run tests with race detection
97+
go test -v -race ./...
98+
99+
# Run tests with coverage
100+
go test -v -race -coverprofile=coverage.out ./...
101+
102+
# Run tests with container logs
103+
CONTAINER_LOG=true go test -v ./...
104+
```
105+
106+
### Running Linter Locally
107+
```bash
108+
# Install golangci-lint
109+
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
110+
111+
# Run linter
112+
golangci-lint run
113+
114+
# Run linter with auto-fix
115+
golangci-lint run --fix
116+
```
117+
118+
## Troubleshooting
119+
120+
### Docker Issues in CI
121+
If tests fail due to Docker issues in CI:
122+
1. Check GitHub Actions runner status
123+
2. Verify Docker is available in the runner
124+
3. Check Testcontainers logs
125+
126+
### Timeout Issues
127+
If tests timeout in CI:
128+
1. Increase timeout in workflow (currently 10m)
129+
2. Check Quickwit container startup time
130+
3. Verify network connectivity
131+
132+
### Coverage Upload Failures
133+
Coverage upload to Codecov is set to `continue-on-error: true`, so failures won't break the build.
134+
135+
To enable Codecov:
136+
1. Sign up at https://codecov.io
137+
2. Add repository
138+
3. No token needed for public repositories

‎.github/CONTRIBUTING.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Contributing to quickwit-go
2+
3+
Thank you for your interest in contributing to quickwit-go! 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/quickwit-go.git`
9+
3. Create a new branch: `git checkout -b feature/your-feature-name`
10+
4. Make your changes
11+
5. Run tests: `go test -v ./...`
12+
6. Run linter: `golangci-lint run`
13+
7. Commit your changes: `git commit -am 'Add some feature'`
14+
8. Push to the branch: `git push origin feature/your-feature-name`
15+
9. Create a Pull Request
16+
17+
## Development Setup
18+
19+
### Prerequisites
20+
21+
- Go 1.24 or later
22+
- Docker (for running integration tests)
23+
- golangci-lint (for linting)
24+
25+
### Install Dependencies
26+
27+
```bash
28+
go mod download
29+
```
30+
31+
### Running Tests
32+
33+
```bash
34+
# Run all tests
35+
go test -v ./...
36+
37+
# Run tests with race detection
38+
go test -v -race ./...
39+
40+
# Run tests with coverage
41+
go test -v -race -coverprofile=coverage.out ./...
42+
43+
# Run tests with container logs
44+
CONTAINER_LOG=true go test -v ./...
45+
```
46+
47+
### Running Linter
48+
49+
```bash
50+
# Install golangci-lint
51+
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
52+
53+
# Run linter
54+
golangci-lint run
55+
56+
# Run linter with auto-fix
57+
golangci-lint run --fix
58+
```
59+
60+
## Code Guidelines
61+
62+
### Go Style
63+
64+
- Follow the [Effective Go](https://golang.org/doc/effective_go) guidelines
65+
- Use `gofmt` to format your code
66+
- Add comments to exported functions, types, and constants
67+
- Keep functions small and focused
68+
- Use meaningful variable and function names
69+
70+
### Testing
71+
72+
- Write tests for all new features
73+
- Maintain or improve code coverage
74+
- Use table-driven tests where appropriate
75+
- Use Testcontainers for integration tests
76+
- Clean up resources in tests (use `defer` or `t.Cleanup()`)
77+
78+
### Commits
79+
80+
- Write clear, concise commit messages
81+
- Use conventional commit format:
82+
- `feat: add new feature`
83+
- `fix: resolve bug`
84+
- `docs: update documentation`
85+
- `test: add tests`
86+
- `refactor: refactor code`
87+
- `chore: update dependencies`
88+
89+
### Pull Requests
90+
91+
- Fill out the Pull Request template
92+
- Ensure all CI checks pass
93+
- Request review from maintainers
94+
- Address review comments promptly
95+
- Keep PRs focused and reasonably sized
96+
97+
## Project Structure
98+
99+
```
100+
quickwit-go/
101+
├── .github/ # GitHub configuration
102+
│ ├── workflows/ # GitHub Actions workflows
103+
│ ├── CI.md # CI documentation
104+
│ ├── CONTRIBUTING.md # This file
105+
│ ├── PULL_REQUEST_TEMPLATE.md
106+
│ └── dependabot.yml # Dependabot configuration
107+
├── model_*.go # Model definitions (one per file)
108+
├── client.go # Client implementation
109+
├── client_test.go # Client tests
110+
├── builder.go # Client builder
111+
├── constants.go # Constants
112+
├── testcontainer.go # Testcontainer setup
113+
├── go.mod # Go module definition
114+
├── go.sum # Go module checksums
115+
├── README.md # Project README
116+
├── TESTING.md # Testing documentation
117+
├── LICENSE # MIT License
118+
└── .golangci.yml # Linter configuration
119+
```
120+
121+
## Adding New Features
122+
123+
When adding new features:
124+
125+
1. **Add the method to the `Client` interface** in `client.go`
126+
2. **Implement the method** in `client.go`
127+
3. **Add models** if needed (create new `model_*.go` files)
128+
4. **Write tests** in `client_test.go`
129+
5. **Update documentation** in README.md and TESTING.md
130+
6. **Run tests and linter** to ensure everything works
131+
132+
### Example: Adding a New Endpoint
133+
134+
```go
135+
// 1. Add to Client interface
136+
type Client interface {
137+
// ... existing methods
138+
NewMethod(ctx context.Context, param string) (*Response, error)
139+
}
140+
141+
// 2. Implement the method
142+
func (c *client) NewMethod(ctx context.Context, param string) (*Response, error) {
143+
req, err := http.NewRequestWithContext(
144+
ctx,
145+
"GET",
146+
fmt.Sprintf("%s/api/v1/new-endpoint?param=%s", c.endpoint, param),
147+
nil,
148+
)
149+
if err != nil {
150+
return nil, err
151+
}
152+
153+
for _, interceptor := range c.interceptors {
154+
interceptor(req)
155+
}
156+
157+
return Request[Response](c.log, req)
158+
}
159+
160+
// 3. Add tests
161+
func TestClient(t *testing.T) {
162+
// ... setup
163+
164+
t.Run("New Method", func(t *testing.T) {
165+
result, err := client.NewMethod(ctx, "test-param")
166+
require.NoError(t, err)
167+
assert.NotNil(t, result)
168+
})
169+
}
170+
```
171+
172+
## Reporting Issues
173+
174+
- Use the GitHub issue tracker
175+
- Check if the issue already exists
176+
- Provide a clear description
177+
- Include steps to reproduce
178+
- Include Go version and OS information
179+
- Include relevant logs and error messages
180+
181+
## Questions?
182+
183+
- Open a GitHub issue with the "question" label
184+
- Check existing issues and documentation first
185+
186+
## License
187+
188+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## Description
2+
3+
<!-- Describe your changes in detail -->
4+
5+
## Type of change
6+
7+
- [ ] Bug fix (non-breaking change which fixes an issue)
8+
- [ ] New feature (non-breaking change which adds functionality)
9+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
10+
- [ ] Documentation update
11+
12+
## How Has This Been Tested?
13+
14+
<!-- Please describe the tests that you ran to verify your changes -->
15+
16+
- [ ] Test A
17+
- [ ] Test B
18+
19+
## Checklist
20+
21+
- [ ] My code follows the style guidelines of this project
22+
- [ ] I have performed a self-review of my own code
23+
- [ ] I have commented my code, particularly in hard-to-understand areas
24+
- [ ] I have made corresponding changes to the documentation
25+
- [ ] My changes generate no new warnings
26+
- [ ] I have added tests that prove my fix is effective or that my feature works
27+
- [ ] New and existing unit tests pass locally with my changes
28+
- [ ] Any dependent changes have been merged and published in downstream modules

‎.github/dependabot.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
version: 2
2+
updates:
3+
# Enable version updates for Go modules
4+
- package-ecosystem: "gomod"
5+
directory: "/"
6+
schedule:
7+
interval: "weekly"
8+
open-pull-requests-limit: 10
9+
labels:
10+
- "dependencies"
11+
- "go"
12+
13+
# Enable version updates for GitHub Actions
14+
- package-ecosystem: "github-actions"
15+
directory: "/"
16+
schedule:
17+
interval: "weekly"
18+
open-pull-requests-limit: 10
19+
labels:
20+
- "dependencies"
21+
- "github-actions"

0 commit comments

Comments
 (0)