Contributing#

Thank you for your interest in contributing to GeoServer CLI!

Development Setup#

Prerequisites#

• Go 1.24 or later
• Git
• Make (optional)

Getting Started#

1. Clone the repository:

   1 2	git clone https://gitlab.com/aice/geoserver-cli.git cd geoserver-cli

2. Install development tools:

   1 2	./scripts/setup-git-hooks.sh ./scripts/install-tools.sh

3. Build the project:

   1	go build -o geoserver-cli ./cmd/geoserver-cli

4. Run tests:

   1	go test ./...

Code Style#

Formatting#

Code must be formatted with gofmt:

1

gofmt -w .

Linting#

Code must pass golangci-lint:

1

./bin/golangci-lint run ./...

Testing#

All new features should include tests:

1
2
3
4
5
6
7
8

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./internal/geoserver/...

Git Workflow#

1. Create a branch:

   1	git checkout -b feature/my-feature

2. Make changes and commit:

   1 2	git add . git commit -m "Add feature X"

3. Push and create merge request:

   1	git push origin feature/my-feature

Pre-commit Hooks#

The repository uses Git pre-commit hooks to ensure code quality before commits are created. This catches issues early and keeps the commit history clean.

What Gets Checked#

The pre-commit hook automatically runs four checks:

1. Code Formatting (gofmt)

   • Automatically formats all staged .go files
   • Re-stages formatted files
   • Ensures consistent code style

2. Static Analysis (go vet)

   • Detects common mistakes and suspicious constructs
   • Catches bugs like unreachable code, incorrect struct tags, etc.

3. Linting (golangci-lint)

   • Runs comprehensive linting with multiple linters
   • Enforces best practices and style guidelines
   • Requires golangci-lint to be installed (via ./scripts/install-tools.sh)

4. Unit Tests (go test)

   • Runs all unit tests in the repository
   • Ensures new changes don’t break existing functionality

Setup#

The hooks are set up automatically when you run:

1

./scripts/setup-git-hooks.sh

This configures Git to use the .githooks/ directory for hooks.

Verify Setup#

Check that hooks are active:

1
2

git config --get core.hooksPath
# Should output: .githooks

When Checks Fail#

If any check fails, the commit is blocked and you’ll see error messages:

1
2
3

[pre-commit] Formatting (gofmt) staged .go files...
[pre-commit] Lint (go vet)...
# exit status 1

Fix the issues and try committing again:

1
2
3
4
5
6
7
8

# Fix the issues
go vet ./...        # Run manually to see errors
gofmt -w .          # Format all files
golangci-lint run   # Run linter

# Try committing again
git add .
git commit -m "Your message"

Bypassing Hooks (Not Recommended)#

In rare cases, you can skip hooks with:

1

git commit --no-verify -m "Your message"

Warning: This bypasses all quality checks. Use only for emergency fixes or when hooks are incorrectly failing. CI will still catch issues.

Code Organization#

Package Structure#

1
2
3
4
5
6
7

cmd/geoserver-cli/     # CLI entrypoint
internal/
  cli/                 # Cobra commands
  config/              # Configuration management
  geoserver/           # GeoServer REST client
  postgis/             # PostGIS client
  qgis/                # QGIS export utilities

Adding New Commands#

1. Create command function in internal/cli/
2. Add to root command in internal/cli/root.go
3. Add tests in *_test.go files
4. Update documentation

Adding New Features#

1. Implement in appropriate internal/ package
2. Add unit tests
3. Add CLI command (if user-facing)
4. Update documentation
5. Add examples

Documentation#

Code Documentation#

• Use Go doc comments for exported functions
• Follow Go documentation conventions
• Include examples in doc comments when helpful

User Documentation#

• Update docs/ directory for user-facing changes
• Add examples for new commands
• Update guides for new workflows

Testing Guidelines#

Unit Tests#

• Test all exported functions
• Use httptest for HTTP client tests
• Mock external dependencies
• Aim for >80% code coverage

Integration Tests#

• Test against real GeoServer instances (optional)
• Use test containers or local GeoServer
• Document test setup requirements

Commit Messages#

Follow conventional commit format:

1
2
3
4

feat: Add new publish command for Shapefiles
fix: Correct PostGIS connection parameter handling
docs: Update QGIS authentication guide
test: Add tests for layer update command

Review Process#

1. Create merge request
2. Ensure CI passes
3. Address review comments
4. Squash commits if requested
5. Merge after approval

Questions?#

• Open an issue for questions
• Check existing issues for similar questions
• Review code comments and documentation

Thank you for contributing!