From 5f2a8e5be493fe3e96dfa8f2179f5939938d9e47 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 20:08:05 +0000
Subject: [PATCH 1/2] Initial plan


From ef3e4cc2919f64a48e55b21b088821127829ad43 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 14 Feb 2026 20:10:08 +0000
Subject: [PATCH 2/2] docs: add CONTRIBUTING.md and troubleshooting for tag
 push errors

Co-authored-by: christiangda <1197820+christiangda@users.noreply.github.com>
---
 CONTRIBUTING.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  31 ++++++++-
 2 files changed, 202 insertions(+), 1 deletion(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..2468da8
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,172 @@
+# Contributing to machineid
+
+Thank you for your interest in contributing to machineid! This document provides guidelines and best practices for contributing to the project.
+
+## Development Setup
+
+### Prerequisites
+
+- Go 1.22 or higher
+- Git
+- Make
+
+### Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/machineid.git
+   cd machineid
+   ```
+
+3. Add the upstream repository:
+   ```bash
+   git remote add upstream https://github.com/slashdevops/machineid.git
+   ```
+
+4. Create a new branch for your changes:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+## Development Workflow
+
+### Building
+
+Build the project using the provided Makefile:
+
+```bash
+make build
+```
+
+### Testing
+
+Run the test suite:
+
+```bash
+make test
+```
+
+Run tests with coverage:
+
+```bash
+make test-coverage
+```
+
+### Linting
+
+Run the linter to ensure code quality:
+
+```bash
+make lint
+```
+
+## Versioning and Releases
+
+This project follows [Semantic Versioning 2.0.0](https://semver.org/). Version numbers follow the format `MAJOR.MINOR.PATCH`:
+
+- **MAJOR**: Incompatible API changes
+- **MINOR**: Backwards-compatible functionality additions
+- **PATCH**: Backwards-compatible bug fixes
+
+### Creating Tags
+
+**Important**: Tags must follow semantic versioning order. You cannot create a tag with an older version number than existing tags.
+
+#### Example Error
+
+If you try to create `v0.0.1` when `v0.0.2` already exists, you'll get:
+
+```
+! [remote rejected] v0.0.1 -> v0.0.1 (push declined due to repository rule violations)
+error: failed to push some refs to 'github.com:slashdevops/machineid.git'
+```
+
+This is a GitHub repository rule that prevents version rollback and ensures proper version ordering.
+
+#### Correct Versioning Workflow
+
+1. Check existing tags:
+   ```bash
+   git tag -l
+   ```
+
+2. Create the next appropriate version tag:
+   ```bash
+   # If the latest tag is v0.0.2, create v0.0.3 or higher
+   git tag -a "v0.0.3" -m "Release v0.0.3"
+   ```
+
+3. Push the tag:
+   ```bash
+   git push origin v0.0.3
+   ```
+
+#### Version Increment Guidelines
+
+Choose the appropriate version increment based on your changes:
+
+- **Patch** (e.g., `v0.0.2` → `v0.0.3`): Bug fixes, documentation updates
+- **Minor** (e.g., `v0.0.2` → `v0.1.0`): New features, backwards-compatible changes
+- **Major** (e.g., `v0.0.2` → `v1.0.0`): Breaking changes, incompatible API modifications
+
+### Release Process
+
+1. Ensure all tests pass:
+   ```bash
+   make test
+   ```
+
+2. Update documentation if needed
+
+3. Create and push a tag with the next appropriate version:
+   ```bash
+   git tag -a "vX.Y.Z" -m "Release vX.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+4. The GitHub Actions workflow will automatically create a release with binaries
+
+## Code Style
+
+Follow Go's idiomatic style as defined in:
+- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
+- [Effective Go](https://golang.org/doc/effective_go.html)
+- [Google Go Style Guide](https://google.github.io/styleguide/go/)
+
+### Key Guidelines
+
+- Use meaningful names for variables, functions, and packages
+- Keep functions small and focused on a single task
+- Use comments to explain complex logic or decisions
+- Prefer `any` over `interface{}` for better readability
+- Use dependency injection for services to facilitate testing
+
+## Pull Request Process
+
+1. Update documentation for any new features or changes
+2. Ensure all tests pass
+3. Ensure code passes linting
+4. Update the README.md if needed
+5. Submit a pull request with a clear description of changes
+
+### Pull Request Title
+
+Use conventional commit format:
+
+- `feat:` for new features
+- `fix:` for bug fixes
+- `docs:` for documentation changes
+- `test:` for test-related changes
+- `chore:` for maintenance tasks
+
+Example: `feat: add support for custom MAC address filters`
+
+## Questions?
+
+If you have questions or need help, please:
+- Open an issue on GitHub
+- Check existing issues for similar questions
+- Review the README.md for usage examples
+
+Thank you for contributing to machineid!
diff --git a/README.md b/README.md
index c74f469..9df85f7 100644
--- a/README.md
+++ b/README.md
@@ -489,9 +489,38 @@ id, _ := machineid.New().
     ID()
 ```
 
+## Troubleshooting
+
+### Git Tag Push Error: "push declined due to repository rule violations"
+
+If you encounter this error when trying to push a tag:
+
+```
+! [remote rejected] v0.0.1 -> v0.0.1 (push declined due to repository rule violations)
+error: failed to push some refs to 'github.com:slashdevops/machineid.git'
+```
+
+**Cause**: This happens when you try to create a tag with a version number that is older than existing tags. GitHub repository rules enforce semantic versioning order to prevent version rollback.
+
+**Solution**: Create a tag with a version number higher than all existing tags.
+
+1. Check existing tags:
+   ```bash
+   git tag -l
+   ```
+
+2. Create the next appropriate version:
+   ```bash
+   # If the latest tag is v0.0.2, use v0.0.3 or higher
+   git tag -a "v0.0.3" -m "Release v0.0.3"
+   git push origin v0.0.3
+   ```
+
+For more information about versioning and releases, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Contributing
 
-Contributions are welcome. Please open an issue or submit a pull request.
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute, including information about versioning, testing, and code style.
 
 ## License