From e39b0261f38bfb05d72e919157da80621f9a5652 Mon Sep 17 00:00:00 2001 From: ProtoTess <32490978+0x524A@users.noreply.github.com> Date: Tue, 11 Nov 2025 03:45:30 +0000 Subject: [PATCH] feat: add contribution guidelines and issue templates for better community engagement --- .github/CONTRIBUTING.md | 275 ++++++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 102 +++++++ .../ISSUE_TEMPLATE/camera_compatibility.yml | 86 ++++++ .github/ISSUE_TEMPLATE/config.yml | 11 + .github/ISSUE_TEMPLATE/feature_request.yml | 75 +++++ .github/pull_request_template.md | 79 +++++ README.md | 47 ++- 7 files changed, 673 insertions(+), 2 deletions(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/camera_compatibility.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..a6c656d --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -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. ๐Ÿš€ diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..84b474a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/camera_compatibility.yml b/.github/ISSUE_TEMPLATE/camera_compatibility.yml new file mode 100644 index 0000000..e3f6858 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/camera_compatibility.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..871434d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..b38acbf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..e03ef4d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,79 @@ +## Description + + +## Type of Change + + +- [ ] ๐Ÿ› 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 + + +Fixes # +Relates to # + +## Changes Made + + +- +- +- + +## Testing Performed + + +- [ ] 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) + + +- **Camera Model**: +- **Firmware Version**: +- **Test Results**: + +## Documentation + + +- [ ] Code comments added/updated +- [ ] README.md updated +- [ ] Examples added/updated +- [ ] API documentation (GoDoc) updated +- [ ] CHANGELOG.md updated + +## Checklist + + +- [ ] 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 + + +## Screenshots/Examples + + +```go +// Example usage +``` + +## Additional Context + + +## Reviewer Notes + diff --git a/README.md b/README.md index 7b30743..1f8c737 100644 --- a/README.md +++ b/README.md @@ -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