Skip to content

Commit e9ee2f4

Browse files
ArdakilicCopilot
Ardakilic
and
Copilot
authored
Feature: Implement Self-Update Feature with Comprehensive Testing and Documentation (#10)
* wip: self-update feature * chore: mock http client * chore: fix unit tests * Update main.go Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 75a8ad5 commit e9ee2f4

6 files changed

Lines changed: 2636 additions & 291 deletions

File tree

‎Development.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# Development Guide
2+
3+
This guide covers development workflows, building, testing, and deployment for the FLAC to 16-bit Converter.
4+
5+
## Setting Version During Build
6+
7+
The application version is embedded at build time using Go's `-ldflags` with the `-X` flag. This version is used by the `--self-update` feature to determine if updates are available.
8+
9+
### Method 1: Manual Version Setting
10+
11+
Set a specific version during build:
12+
13+
```bash
14+
# Set version to v1.2.3
15+
go build -ldflags="-X main.version=v1.2.3" -o flac-converter .
16+
17+
# Use environment variable
18+
VERSION=v1.2.3 go build -ldflags="-X main.version=$VERSION" -o flac-converter .
19+
```
20+
21+
### Method 2: Using Git Tags (Recommended)
22+
23+
The Makefile automatically uses git tags for versioning:
24+
25+
```bash
26+
# Create and push a git tag
27+
git tag v1.0.0
28+
git push origin v1.0.0
29+
30+
# Build with automatic version detection
31+
make build
32+
# or
33+
go build -ldflags="-X main.version=$(git describe --tags --always --dirty)" -o flac-converter .
34+
```
35+
36+
The `git describe` command will output something like:
37+
- `v1.0.0` (exact tag match)
38+
- `v1.0.0-1-g1234567` (1 commit after tag)
39+
- `v1.0.0-dirty` (uncommitted changes)
40+
41+
### Method 3: Using Makefile
42+
43+
The Makefile provides convenient targets:
44+
45+
```bash
46+
# Build for current platform with git version
47+
make build
48+
49+
# Build for all platforms
50+
make build-all
51+
52+
# Clean and rebuild
53+
make clean && make build
54+
```
55+
56+
## Development Workflow
57+
58+
### Prerequisites
59+
60+
- Go 1.25.1 or later
61+
- Git
62+
- Make (optional, for convenience)
63+
- Docker (for containerized testing)
64+
- golangci-lint (for linting)
65+
66+
### Setting Up Development Environment
67+
68+
```bash
69+
# Clone the repository
70+
git clone https://github.com/Ardakilic/flac-to-16bit-converter.git
71+
cd flac-to-16bit-converter
72+
73+
# Install dependencies
74+
go mod download
75+
76+
# Run tests
77+
make test
78+
# or
79+
go test -v ./...
80+
81+
# Build for development
82+
make build
83+
```
84+
85+
### Code Quality
86+
87+
```bash
88+
# Format code
89+
make fmt
90+
# or
91+
go fmt ./...
92+
93+
# Lint code
94+
make lint
95+
# or
96+
golangci-lint run
97+
98+
# Run tests with coverage
99+
go test -cover ./...
100+
```
101+
102+
## Testing
103+
104+
### Running Tests
105+
106+
```bash
107+
# Run all tests
108+
go test ./...
109+
110+
# Run tests with verbose output
111+
go test -v ./...
112+
113+
# Run tests with coverage
114+
go test -cover ./...
115+
116+
# Generate coverage report
117+
go test -coverprofile=coverage.out ./...
118+
go tool cover -html=coverage.out
119+
```
120+
121+
### Test Coverage
122+
123+
Current test coverage: ~68%
124+
125+
Key test areas:
126+
- Version comparison logic
127+
- Audio file processing
128+
- Docker integration
129+
- Self-update functionality
130+
- Error handling
131+
132+
## Building for Different Platforms
133+
134+
### Single Platform Build
135+
136+
```bash
137+
# Linux x64
138+
GOOS=linux GOARCH=amd64 go build -ldflags="-X main.version=v1.0.0" -o flac-converter-linux-amd64 .
139+
140+
# Windows x64
141+
GOOS=windows GOARCH=amd64 go build -ldflags="-X main.version=v1.0.0" -o flac-converter-windows-amd64.exe .
142+
143+
# macOS ARM64
144+
GOOS=darwin GOARCH=arm64 go build -ldflags="-X main.version=v1.0.0" -o flac-converter-darwin-arm64 .
145+
146+
# Linux ARM64
147+
GOOS=linux GOARCH=arm64 go build -ldflags="-X main.version=v1.0.0" -o flac-converter-linux-arm64 .
148+
```
149+
150+
### Cross-Platform Build (Using Makefile)
151+
152+
```bash
153+
# Build for all supported platforms
154+
make build-all
155+
156+
# Create distribution packages
157+
make package
158+
```
159+
160+
This creates binaries in the `dist/` directory with proper naming and compression.
161+
162+
## Self-Update Feature
163+
164+
The self-update feature uses the embedded version to:
165+
166+
1. Check current version against GitHub releases
167+
2. Download platform-specific binaries
168+
3. Replace the running binary safely
169+
170+
### Version Format
171+
172+
The version should follow semantic versioning:
173+
- `v1.0.0` - major.minor.patch
174+
- `v1.0.0-rc.1` - release candidate
175+
- `v1.0.0-dev` - development version
176+
177+
### Testing Self-Update
178+
179+
```bash
180+
# Test with development version (skips update)
181+
go build -ldflags="-X main.version=dev" -o flac-converter .
182+
./flac-converter --self-update
183+
184+
# Test with specific version
185+
go build -ldflags="-X main.version=v1.0.0" -o flac-converter .
186+
./flac-converter --self-update
187+
```
188+
189+
## Release Process
190+
191+
### Creating a Release
192+
193+
1. Update version in code/docs if needed
194+
2. Create and push git tag:
195+
```bash
196+
git tag v1.0.0
197+
git push origin v1.0.0
198+
```
199+
3. GitHub Actions will automatically build and create release
200+
4. Update release notes with changes
201+
202+
### Pre-release Builds
203+
204+
For development/testing releases:
205+
206+
```bash
207+
# Build with pre-release version
208+
go build -ldflags="-X main.version=v1.0.0-rc.1" -o flac-converter .
209+
210+
# Or use git describe for automatic pre-release detection
211+
make build # Will include commit hash if not on exact tag
212+
```
213+
214+
## Docker Development
215+
216+
### Building Docker Image
217+
218+
```bash
219+
# Build the Docker image for testing
220+
docker build -t flac-converter-test .
221+
222+
# Run tests in Docker
223+
docker run --rm flac-converter-test go test ./...
224+
```
225+
226+
### Using Docker for SoX
227+
228+
The application supports using Docker for SoX operations:
229+
230+
```bash
231+
# Build with Docker support
232+
./flac-converter /source/dir --use-docker --docker-image ardakilic/sox_ng:latest
233+
```
234+
235+
## Debugging
236+
237+
### Enable Debug Output
238+
239+
The application uses standard Go logging. For more verbose output:
240+
241+
```bash
242+
# Run with debug flags if implemented
243+
./flac-converter --verbose /source/dir
244+
```
245+
246+
### Common Issues
247+
248+
1. **Version not updating**: Ensure you're using `-ldflags="-X main.version=..."` during build
249+
2. **Self-update fails**: Check network connectivity and GitHub API access
250+
3. **Cross-platform builds**: Use correct GOOS/GOARCH combinations
251+
4. **Docker issues**: Ensure Docker is running and accessible
252+
253+
## Contributing
254+
255+
1. Fork the repository
256+
2. Create a feature branch
257+
3. Make changes with tests
258+
4. Ensure all tests pass: `make test`
259+
5. Format code: `make fmt`
260+
6. Submit pull request
261+
262+
## CI/CD
263+
264+
The project uses GitHub Actions for:
265+
- Automated testing on all platforms
266+
- Cross-platform builds
267+
- Release creation
268+
- Code quality checks
269+
270+
Workflow files are in `.github/workflows/`.

‎README.md‎

Lines changed: 21 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ flac-converter <source_directory> [options]
7777
--copy-images Copy JPG and PNG files
7878
--use-docker Use Docker to run Sox instead of local installation
7979
--docker-image <img> Specify Docker image (default: ardakilic/sox_ng:latest)
80+
--self-update Check for updates and self-update if newer version available
8081
```
8182

8283
### Examples:
@@ -99,6 +100,11 @@ flac-converter.exe "C:\Music\MyAlbum" --target-dir "C:\Music\MyAlbum-16bit" --us
99100
./flac-converter ~/Music/MyAlbum --target-dir ~/Music/MyAlbum-16bit --use-docker
100101
```
101102

103+
Check for updates:
104+
```bash
105+
flac-converter --self-update
106+
```
107+
102108
## Docker Support
103109

104110
When using the `--use-docker` option:
@@ -139,12 +145,16 @@ Alternative Docker images you can use:
139145

140146
## Development
141147

142-
### Requirements
148+
For detailed development information, including advanced build options, testing procedures, and contribution guidelines, see [Development.md](Development.md).
149+
150+
### Quick Start
151+
152+
#### Requirements
143153

144154
- Go 1.24.5 or later
145155
- Make (optional, for convenience)
146156

147-
### Building
157+
#### Building
148158

149159
```bash
150160
# Clone the repository
@@ -158,7 +168,7 @@ go build -o flac-converter .
158168
make build
159169
```
160170

161-
### Testing
171+
#### Testing
162172

163173
```bash
164174
# Run tests
@@ -168,39 +178,20 @@ go test -v ./...
168178
make test
169179
```
170180

171-
### Building for Different Platforms
172-
173-
```bash
174-
# Linux x64
175-
GOOS=linux GOARCH=amd64 go build -o flac-converter-linux-amd64 .
176-
177-
# Windows x64
178-
GOOS=windows GOARCH=amd64 go build -o flac-converter-windows-amd64.exe .
181+
### Setting Version for Self-Update
179182

180-
# macOS ARM64 (Apple Silicon)
181-
GOOS=darwin GOARCH=arm64 go build -o flac-converter-darwin-arm64 .
182-
183-
# Linux ARM64
184-
GOOS=linux GOARCH=arm64 go build -o flac-converter-linux-arm64 .
185-
186-
# Build all platforms at once
187-
make build-all
188-
```
189-
190-
### Code Quality
183+
To enable the self-update feature, set the version during build:
191184

192185
```bash
193-
# Format code
194-
go fmt ./...
186+
# Set specific version
187+
go build -ldflags="-X main.version=v1.2.3" -o flac-converter .
195188

196-
# Run linter (requires golangci-lint)
197-
golangci-lint run
198-
199-
# Or use Make
200-
make fmt
201-
make lint
189+
# Use git tags (recommended)
190+
make build # Automatically uses git describe for versioning
202191
```
203192

193+
See [Development.md](Development.md) for detailed version management and build options.
194+
204195
### CI/CD
205196

206197
The project uses GitHub Actions to automatically build binaries for all supported platforms on every commit. The workflow:

‎flac-converter.old‎

8.88 MB
Binary file not shown.

0 commit comments

Comments
 (0)