feat: add contribution guidelines and issue templates for better community engagement

This commit is contained in:
ProtoTess
2025-11-11 03:45:30 +00:00
parent 917a6d4dc4
commit e39b0261f3
7 changed files with 673 additions and 2 deletions
+275
View File
@@ -0,0 +1,275 @@
# Contributing to go-onvif
Thank you for your interest in contributing to go-onvif! 🎉
## Code of Conduct
This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please be respectful and considerate in all interactions.
## How Can I Contribute?
### Reporting Bugs
Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:
- Clear, descriptive title
- Steps to reproduce the issue
- Expected vs actual behavior
- Code samples
- Your environment (Go version, OS, camera model)
- Error messages or logs
### Suggesting Features
Feature requests are welcome! Please:
- Use a clear, descriptive title
- Provide detailed description of the proposed feature
- Explain the use case and benefits
- Consider if the feature fits the project scope
### Camera Compatibility Reports
Help us maintain compatibility information:
- Report both working and non-working cameras
- Include manufacturer, model, and firmware version
- Run `onvif-diagnostics` and share the output
- Note any special configuration needed
### Pull Requests
#### Before Submitting
1. Check if there's an existing PR for the same change
2. For major changes, open an issue first to discuss
3. Ensure your code follows the project style
4. Add tests for new functionality
5. Update documentation as needed
#### Submission Process
1. **Fork** the repository
2. **Create** a feature branch from `main`:
```bash
git checkout -b feature/amazing-feature
```
3. **Make** your changes:
- Write clear, descriptive commit messages
- Follow Go best practices and idioms
- Add comments for complex logic
- Include tests
4. **Test** your changes:
```bash
make test
make lint
```
5. **Commit** using conventional commits:
```bash
git commit -m "feat: add GetAnalyticsConfigurations support"
git commit -m "fix: correct PTZ coordinate calculation"
git commit -m "docs: update README with new examples"
```
6. **Push** to your fork:
```bash
git push origin feature/amazing-feature
```
7. **Open** a Pull Request with:
- Clear title and description
- Reference related issues
- List of changes made
- Testing performed
## Development Setup
### Prerequisites
- Go 1.21 or later
- Make (optional, for Makefile targets)
- golangci-lint for linting
### Clone and Build
```bash
git clone https://github.com/0x524A/go-onvif.git
cd go-onvif
go build ./...
```
### Running Tests
```bash
# Run all tests
make test
# Run tests with coverage
make test-coverage
# Run tests with race detection
go test -race ./...
# Run specific package tests
go test ./discovery/...
```
### Linting
```bash
make lint
```
## Coding Standards
### Go Style
- Follow [Effective Go](https://golang.org/doc/effective_go)
- Use `gofmt` for formatting
- Keep functions focused and small
- Write self-documenting code
### Naming Conventions
- Use descriptive variable names
- Follow Go naming conventions (camelCase for private, PascalCase for public)
- Avoid abbreviations unless widely understood
### Error Handling
- Always check errors
- Provide context in error messages
- Use `fmt.Errorf` with `%w` for error wrapping
### Documentation
- Add GoDoc comments for all exported types and functions
- Include usage examples for complex features
- Update README.md when adding new features
### Testing
- Write table-driven tests when applicable
- Test both success and failure cases
- Mock external dependencies
- Aim for >80% coverage for new code
### Example Test
```go
func TestGetDeviceInformation(t *testing.T) {
tests := []struct {
name string
setup func(*testing.T) *Client
want *DeviceInformation
wantErr bool
}{
{
name: "success",
setup: func(t *testing.T) *Client {
// Setup mock
},
want: &DeviceInformation{
Manufacturer: "Test",
},
wantErr: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
client := tt.setup(t)
got, err := client.GetDeviceInformation(context.Background())
if (err != nil) != tt.wantErr {
t.Errorf("error = %v, wantErr %v", err, tt.wantErr)
return
}
if !reflect.DeepEqual(got, tt.want) {
t.Errorf("got %v, want %v", got, tt.want)
}
})
}
}
```
## Commit Message Guidelines
We use [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation changes
- `test:` - Test additions or modifications
- `refactor:` - Code refactoring
- `perf:` - Performance improvements
- `chore:` - Maintenance tasks
Examples:
```
feat: add support for Event service
fix: correct PTZ velocity calculation in ContinuousMove
docs: add examples for imaging settings
test: add integration tests for Hikvision cameras
```
## Project Structure
```
go-onvif/
├── client.go # Main ONVIF client
├── types.go # ONVIF type definitions
├── device.go # Device service
├── media.go # Media service
├── ptz.go # PTZ service
├── imaging.go # Imaging service
├── soap/ # SOAP client
├── discovery/ # WS-Discovery
├── server/ # ONVIF server implementation
├── testing/ # Test utilities
├── testdata/ # Test fixtures
├── cmd/ # Command-line tools
└── examples/ # Usage examples
```
## Adding New Features
### Client Features
1. Add method to appropriate service file (device.go, media.go, etc.)
2. Define request/response types in types.go
3. Add tests
4. Update documentation
5. Add example if useful
### Server Features
1. Add handler to server service file
2. Define request/response types
3. Register handler in server.go
4. Add tests
5. Update server documentation
## Review Process
1. Automated checks run on all PRs (tests, linting)
2. Maintainers review code and provide feedback
3. Address review comments
4. Once approved, PR will be merged
## Getting Help
- 💬 [GitHub Discussions](https://github.com/0x524A/go-onvif/discussions) - Ask questions
- 🐛 [GitHub Issues](https://github.com/0x524A/go-onvif/issues) - Report bugs
- 📖 [Documentation](https://pkg.go.dev/github.com/0x524A/go-onvif) - Read the docs
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
---
Thank you for contributing to go-onvif! Your efforts help make ONVIF integration better for everyone. 🚀
+102
View File
@@ -0,0 +1,102 @@
name: 🐛 Bug Report
description: Report a bug or unexpected behavior
title: "[BUG] "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to report this bug! Please fill out the information below.
- type: textarea
id: description
attributes:
label: Description
description: A clear and concise description of what the bug is
placeholder: Describe the bug...
validations:
required: true
- type: textarea
id: reproduce
attributes:
label: Steps to Reproduce
description: Steps to reproduce the behavior
placeholder: |
1. Connect to camera at...
2. Call method...
3. See error...
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected Behavior
description: What you expected to happen
placeholder: I expected...
validations:
required: true
- type: textarea
id: code
attributes:
label: Code Sample
description: Minimal code sample to reproduce the issue
render: go
placeholder: |
package main
import "github.com/0x524A/go-onvif"
func main() {
// Your code here
}
- type: input
id: go-version
attributes:
label: Go Version
description: Output of `go version`
placeholder: go version go1.21.0 linux/amd64
validations:
required: true
- type: input
id: lib-version
attributes:
label: Library Version
description: Git commit hash or release version
placeholder: v1.0.0 or commit abc123
- type: input
id: camera
attributes:
label: Camera Model/Brand
description: If applicable
placeholder: Hikvision DS-2CD2xx, Axis M1065-L, etc.
- type: dropdown
id: os
attributes:
label: Operating System
options:
- Linux
- macOS
- Windows
- Other
validations:
required: true
- type: textarea
id: logs
attributes:
label: Error Output/Logs
description: Paste any error messages or logs
render: shell
- type: textarea
id: context
attributes:
label: Additional Context
description: Any other context about the problem
@@ -0,0 +1,86 @@
name: 📷 Camera Compatibility Report
description: Report compatibility with a specific camera model
title: "[CAMERA] "
labels: ["camera-compatibility"]
body:
- type: markdown
attributes:
value: |
Help us track camera compatibility! Share your experience with a specific camera model.
- type: input
id: manufacturer
attributes:
label: Camera Manufacturer
placeholder: Hikvision, Axis, Dahua, Bosch, etc.
validations:
required: true
- type: input
id: model
attributes:
label: Camera Model
placeholder: DS-2CD2xx, M1065-L, IPC-HDW2xxx, etc.
validations:
required: true
- type: input
id: firmware
attributes:
label: Firmware Version
placeholder: V5.7.3 build 220727
- type: dropdown
id: status
attributes:
label: Compatibility Status
options:
- ✅ Fully Working
- ⚠️ Partially Working
- ❌ Not Working
validations:
required: true
- type: checkboxes
id: features
attributes:
label: Working Features
description: Which features work with this camera?
options:
- label: Device Information
- label: Media Profiles
- label: Stream URIs (RTSP)
- label: Snapshots
- label: PTZ Control
- label: Imaging Settings
- label: Discovery
- type: textarea
id: issues
attributes:
label: Known Issues
description: Describe any issues or limitations
placeholder: PTZ presets don't work, imaging settings return error, etc.
- type: textarea
id: notes
attributes:
label: Additional Notes
description: Any special configuration or workarounds needed
placeholder: Requires authentication, needs specific settings, etc.
- type: checkboxes
id: test-results
attributes:
label: Test Results
description: Have you run the diagnostic tool?
options:
- label: I have run onvif-diagnostics and can attach the output
required: false
- type: textarea
id: diagnostic-output
attributes:
label: Diagnostic Output
description: Paste the output from onvif-diagnostics if available
render: json
+11
View File
@@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: 💬 Discussions
url: https://github.com/0x524A/go-onvif/discussions
about: Ask questions and discuss ideas with the community
- name: 📖 Documentation
url: https://pkg.go.dev/github.com/0x524A/go-onvif
about: Read the API documentation
- name: 📚 Examples
url: https://github.com/0x524A/go-onvif/tree/main/examples
about: Browse code examples
@@ -0,0 +1,75 @@
name: ✨ Feature Request
description: Suggest a new feature or enhancement
title: "[FEATURE] "
labels: ["enhancement"]
body:
- type: markdown
attributes:
value: |
Thank you for suggesting a new feature! Please provide details below.
- type: textarea
id: problem
attributes:
label: Problem Statement
description: Is your feature request related to a problem? Please describe.
placeholder: I'm always frustrated when...
validations:
required: true
- type: textarea
id: solution
attributes:
label: Proposed Solution
description: Describe the solution you'd like
placeholder: I would like to see...
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives Considered
description: Describe any alternative solutions or features you've considered
placeholder: I also considered...
- type: dropdown
id: category
attributes:
label: Feature Category
description: Which area does this feature relate to?
options:
- Client - Device Service
- Client - Media Service
- Client - PTZ Service
- Client - Imaging Service
- Client - Discovery
- Server Implementation
- Documentation
- Testing/Examples
- Performance
- Other
validations:
required: true
- type: textarea
id: use-case
attributes:
label: Use Case
description: Describe your use case for this feature
placeholder: This would help with...
- type: checkboxes
id: contribution
attributes:
label: Contribution
description: Would you be willing to contribute this feature?
options:
- label: I would be willing to submit a PR for this feature
required: false
- type: textarea
id: context
attributes:
label: Additional Context
description: Add any other context, screenshots, or examples
+79
View File
@@ -0,0 +1,79 @@
## Description
<!-- Provide a clear and concise description of your changes -->
## Type of Change
<!-- Mark the relevant option with an "x" -->
- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
- [ ] ✨ New feature (non-breaking change which adds functionality)
- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] 📝 Documentation update
- [ ] 🧪 Test improvements
- [ ] ♻️ Code refactoring
- [ ] ⚡ Performance improvement
## Related Issues
<!-- Link to related issues using #issue_number -->
Fixes #
Relates to #
## Changes Made
<!-- List the main changes in this PR -->
-
-
-
## Testing Performed
<!-- Describe the tests you ran to verify your changes -->
- [ ] Unit tests pass locally
- [ ] Added new tests for new functionality
- [ ] Tested with real ONVIF camera(s)
- [ ] Ran `make lint` with no errors
- [ ] Ran `make test` with all tests passing
### Camera Testing (if applicable)
<!-- If you tested with physical cameras, provide details -->
- **Camera Model**:
- **Firmware Version**:
- **Test Results**:
## Documentation
<!-- Mark what documentation was updated -->
- [ ] Code comments added/updated
- [ ] README.md updated
- [ ] Examples added/updated
- [ ] API documentation (GoDoc) updated
- [ ] CHANGELOG.md updated
## Checklist
<!-- Ensure all items are complete before submitting -->
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published
## Breaking Changes
<!-- If this introduces breaking changes, describe them and migration path -->
## Screenshots/Examples
<!-- If applicable, add screenshots or example code -->
```go
// Example usage
```
## Additional Context
<!-- Add any other context about the PR here -->
## Reviewer Notes
<!-- Any specific areas you'd like reviewers to focus on -->
+45 -2
View File
@@ -1,10 +1,35 @@
# go-onvif
# go-onvif - ONVIF Client and Server Library for Go
[![Go Reference](https://pkg.go.dev/badge/github.com/0x524A/go-onvif.svg)](https://pkg.go.dev/github.com/0x524A/go-onvif)
[![Go Report Card](https://goreportcard.com/badge/github.com/0x524A/go-onvif)](https://goreportcard.com/report/github.com/0x524A/go-onvif)
[![License](https://img.shields.io/github/license/0x524A/go-onvif)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/0x524A/go-onvif)](https://github.com/0x524A/go-onvif/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/0x524A/go-onvif)](https://github.com/0x524A/go-onvif/issues)
A modern, performant, and easy-to-use Go library for communicating with ONVIF-compliant IP cameras and devices. Includes both **ONVIF client** and **ONVIF server** implementations.
> **Modern, high-performance Go library for ONVIF IP camera integration** - Control surveillance cameras, NVRs, and video devices with comprehensive ONVIF Profile S/T/G support. Includes both client and server implementations for complete ONVIF camera simulation and testing.
A production-ready, feature-rich Go (Golang) library for communicating with ONVIF-compliant IP cameras, network video recorders (NVR), and surveillance devices. Perfect for building video management systems (VMS), security camera applications, IoT projects, and camera testing frameworks.
## 🎯 Key Features at a Glance
-**ONVIF Client & Server** - Both client library and virtual camera server
-**Production Ready** - Battle-tested with multiple camera brands
-**Full Protocol Support** - Device, Media, PTZ, Imaging, Discovery services
-**Type Safe** - Comprehensive Go types for all ONVIF operations
-**Well Documented** - Extensive examples and API documentation
-**Camera Tested** - Verified with Hikvision, Axis, Dahua, Bosch cameras
-**Testing Framework** - Built-in mock server and testing utilities
## 🔑 What is ONVIF?
ONVIF (Open Network Video Interface Forum) is an open industry standard for IP-based security products. This library allows you to:
- 🎥 Control IP cameras from any manufacturer (Bosch, Hikvision, Axis, Dahua, etc.)
- 📹 Get RTSP video streams and snapshots
- 🎮 Pan, tilt, and zoom cameras remotely
- 🔧 Configure camera settings (exposure, focus, white balance)
- 🔍 Discover cameras on your network automatically
- 🧪 Test ONVIF implementations without physical hardware
## Features
@@ -497,6 +522,19 @@ go test -v ./testdata/captures/
**See**: `testdata/captures/README.md` for complete testing guide
## 🌟 Star History
If you find this project useful, please consider giving it a star! ⭐
[![Star History Chart](https://api.star-history.com/svg?repos=0x524A/go-onvif&type=Date)](https://star-history.com/#0x524A/go-onvif&Date)
## 📊 Project Stats
![GitHub repo size](https://img.shields.io/github/repo-size/0x524A/go-onvif)
![GitHub code size](https://img.shields.io/github/languages/code-size/0x524A/go-onvif)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/0x524A/go-onvif)
![GitHub last commit](https://img.shields.io/github/last-commit/0x524A/go-onvif)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -512,6 +550,11 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
- 📖 [Documentation](https://pkg.go.dev/github.com/0x524A/go-onvif)
- 🐛 [Issue Tracker](https://github.com/0x524A/go-onvif/issues)
- 💬 [Discussions](https://github.com/0x524A/go-onvif/discussions)
- 🔒 [Security Policy](.github/SECURITY.md)
## Keywords
`onvif` `ip-camera` `surveillance` `golang` `rtsp` `ptz` `camera-control` `video-streaming` `security-camera` `nvr` `vms` `iot` `cctv` `hikvision` `axis` `dahua` `bosch` `camera-sdk` `golang-library` `soap` `ws-discovery`
## Related Projects