🤝 Contribution Guidelines

Hey there! 👋 Thanks for considering contributing to this project! We're excited to have you here!

Whether you're fixing a typo, squashing a bug, or adding a cool new feature - every contribution matters! 🎉

There are just a few things to keep in mind to make sure everything runs smoothly:

🌟 New to Contributing? Start Here!

First time contributing to open source? Welcome! 🎉

We've got you covered with issues tagged as "good first issue" - these are perfect for getting started! They're:

🎯 Well-defined and focused
📚 Have clear acceptance criteria
💡 Include hints or guidance
🚀 Great learning opportunities

How to find them:

Go to Issues
Filter by label: good first issue
Pick one that interests you
Comment on the issue to let others know you're working on it
Follow the development workflow below

Need help? Don't hesitate to ask questions in the issue comments or open a discussion! We're here to help! 💪

🏷️ Issue Labels Explained

🐛 bug - Something isn't working correctly
✨ enhancement - New feature or request
📝 documentation - Improvements or additions to documentation
🌟 good first issue - Good for newcomers
🆘 help wanted - Extra attention is needed
❓ question - Further information is requested
🔄 dependencies - Pull requests that update a dependency file
🚨 priority: high - High priority issues
💥 breaking change - Changes that break backward compatibility

🌿 Branching Strategy

Let's keep things organized! Here's how we handle branches:

🎯 Merge your PR to the dev branch - This is where all the magic happens! (PRs against main will be rejected)
🏠 The main branch is our "production" version - only stable releases here
🚀 The dev branch is where we test new stuff before it goes live

💬 Commit Messages

We use conventional commits - sounds fancy, but it's actually pretty simple!

Examples:

feat: add temperature monitoring for spools 🆕
fix: resolve issue with color visualization 🐛
docs: update README with new sensor info 📝
refactor: improve code structure 🔧

This helps our CI/CD pipeline automatically create releases and changelogs. Pretty cool, right? 🎉

🛠️ Development Environment

🐳 Using the Dev Container (Highly Recommended!)

We've got you covered! This project includes a fully configured Dev Container that sets up everything for you automatically. No more "works on my machine" problems! 🎉

📋 Prerequisites

Docker installed and running 🐋
Visual Studio Code with the Dev Containers extension 💻

🚀 Getting Started

Clone the repository:

git clone https://github.com/Disane87/spoolman-homeassistant.git
cd spoolman-homeassistant

Open in Dev Container:
- Open the project in VS Code
- When prompted, click "Reopen in Container" (or press F1 and select "Dev Containers: Reopen in Container")
- Wait for the container to build and start (first time takes a few minutes)
What's Included:
- ✅ Home Assistant Core - Full Home Assistant instance for testing
- ✅ Python 3.13 - Latest Python with all required dependencies
- ✅ Pre-configured tasks - Start/stop Home Assistant with a single click
- ✅ Linting tools - pylint, black, isort pre-configured
- ✅ Git - Latest version for version control
- ✅ Node.js & npm - For any frontend tooling needs

🎮 Development Workflow

🚀 Start Home Assistant:
- Press Ctrl+Shift+B (or Cmd+Shift+B on Mac)
- Select "startHomeAssistant" task
- Or run: ./scripts/develop in the terminal
- Home Assistant will start at http://localhost:8123 🏠
🛑 Stop Home Assistant:
- Use the "stopHomeAssistant" task
- Or press Ctrl+C in the terminal running Home Assistant
📂 Configuration Location:
- Home Assistant config: /config/ 🏠
- Integration code: /spoolman-homeassistant/custom_components/spoolman/ 📝
- Logs: /config/home-assistant.log 📋
🧪 Testing Your Changes:
- Make changes to the integration code ✏️
- Restart Home Assistant (stop + start) 🔄
- Check logs for any errors: tail -f /config/home-assistant.log 🔍
- Configure the integration at http://localhost:8123/config/integrations

🧪 Running Tests:

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_sensor.py

# Run with coverage
pytest --cov=custom_components.spoolman tests/

✨ Linting and Code Quality:

# Run pylint
./scripts/lint

# Format code with black
black custom_components/spoolman/

# Sort imports
isort custom_components/spoolman/

🔗 Connecting to a Spoolman Instance

You'll need a running Spoolman instance to test the integration. Here are your options:

Option 1: Use Docker (Recommended) 🐋

docker run -d \
  --name spoolman \
  -p 7912:8000 \
  -v spoolman_data:/home/app/.local/share/spoolman \
  ghcr.io/donkie/spoolman:latest

Option 2: Use existing Spoolman instance 🌐

Point the integration to your existing Spoolman URL during setup

🐛 Debugging

📝 Enable Debug Logging: Add to /config/configuration.yaml:

logger:
  default: info
  logs:
    custom_components.spoolman: debug

🔍 Use VS Code Debugger:
- Set breakpoints in your code 🎯
- Use the included launch configuration "Python: Home Assistant"
- Press F5 to start debugging
- Step through your code like a pro! 😎

📋 Check Logs:

# Follow logs in real-time
tail -f /config/home-assistant.log

# Search for errors
grep -i "error" /config/home-assistant.log

# Filter integration logs
grep "spoolman" /config/home-assistant.log

📁 Folder Structure

Here's what goes where (so you don't get lost! 🗺️):

/spoolman-homeassistant/
├── custom_components/
│   └── spoolman/              # Main integration code
│       ├── __init__.py        # Integration setup
│       ├── sensor.py          # Sensor platform
│       ├── coordinator.py     # Data update coordinator
│       ├── config_flow.py     # Configuration flow
│       ├── select.py          # Location select entity
│       ├── services.yaml      # Service definitions
│       ├── manifest.json      # Integration manifest
│       └── sensors/           # Individual sensor classes (27 files)
├── config/                    # Home Assistant config directory
├── tests/                     # Unit tests
├── scripts/                   # Helper scripts
│   ├── develop               # Start Home Assistant
│   ├── lint                  # Run linting
│   └── setup                 # Setup development environment
├── .devcontainer/            # Dev Container configuration
└── docs/                     # Documentation

🔄 Updating Home Assistant in Dev Container

Want to test with a newer Home Assistant version? No problem! Here's how:

Option 1: Update Python Package (Quick) ⚡

# Update to latest stable
pip install --upgrade homeassistant

# Or install specific version
pip install homeassistant==2024.11.0

# Restart Home Assistant after update
./scripts/develop

Option 2: Rebuild Dev Container (Clean) 🧹

# Exit and rebuild container
# In VS Code: Press F1 → "Dev Containers: Rebuild Container"
# Or rebuild from command line:
docker-compose -f .devcontainer/docker-compose.yml build --no-cache

🔍 Check Home Assistant Version:

# In terminal
hass --version

# Or in Home Assistant UI
# Settings → System → About

📦 Update All Dependencies:

# Update all Python packages
pip install --upgrade -r requirements.txt

# Verify integration dependencies
pip list | grep -E "homeassistant|aiohttp|pillow"

💡 Tips & Tricks

Little things that'll save you time:

⚡ Reload Integration: Instead of restarting HA completely, use Developer Tools → YAML → Reload "Custom Integrations" (much faster!)
🧹 Clear Cache: Delete /config/.storage/core.config_entries if you need to reconfigure the integration from scratch
📊 Monitor Performance: Use Home Assistant's built-in performance monitoring tools to see how your changes affect speed
📝 Entity Registry: Check /config/.storage/core.entity_registry to see what entities are registered
🐍 Python Cache: Clear __pycache__ folders if you get weird import issues: find . -type d -name __pycache__ -exec rm -rf {} +
🗄️ Database Reset: Delete /config/home-assistant_v2.db to start fresh (warning: loses all history!)

🏠 Alternative: Local Development (Without Container)

Prefer to keep things local? That's cool too! Here's how:

📋 Requirements:
- Python 3.11 or higher
- Home Assistant Core installed
- Git

Setup:

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Link integration to your HA config
ln -s $(pwd)/custom_components/spoolman ~/.homeassistant/custom_components/spoolman

Start Home Assistant:
```
hass -c ~/.homeassistant
```

💡 Note: We really recommend the Dev Container approach - it just works! But hey, you do you! 😊

CI/CD Requirements

Adhering to these guidelines is crucial because our CI/CD pipeline depends on this workflow. The dev branch is used for testing and validation, while main is reserved for stable releases.

General Guidelines

Code Quality:
- Ensure your code is clean, well-documented, and follows the project’s coding standards.
- Write clear, concise, and descriptive comments where necessary.
- Refactor code where needed to maintain readability and simplicity.
Testing:
- Write unit tests for your code to ensure functionality.
- Run all existing tests to make sure your changes do not break any existing functionality.
- Ensure your code passes the CI tests before submitting a PR.
Documentation:
- Update the documentation to reflect any changes in the code.
- Ensure new features or changes are documented with examples and usage instructions.
Issue Tracking:
- Reference any relevant issues in your commit messages and PR descriptions.
- Use keywords like "fixes" or "closes" followed by the issue number to link PRs to issues.
Code Reviews:
- Be responsive to feedback from code reviewers and make necessary changes promptly.
- Review others' PRs if you have the expertise and provide constructive feedback.
Style Guidelines:
- Follow the established coding style of the project. Consistency is key.
- Use linting tools provided in the project to maintain code style.
Communication:
- Be respectful and considerate in all communications.
- Discuss any significant changes or new features with the project maintainers before starting work to ensure alignment with project goals.

🎖️ Recognition

We value all contributions! Contributors will be:

📋 Listed in our README.md (via our automated contributor workflow)
🏆 Mentioned in release notes for significant contributions
⭐ Featured in our GitHub contributors page

🤖 Automated Workflows

This project uses several GitHub Actions to make contributing easier:

✅ Auto-labeling: Area labels added automatically based on changes
✅ PR validation: Checks for conventional commits, target branch, linked issues
✅ Size labeling: PRs automatically tagged by size
✅ Welcome messages: First-time contributors get helpful guidance
✅ Stale issue management: Old good first issues are cleaned up automatically

See our Automations Guide for full details!

📚 Additional Resources

💬 Community

Issues: Report bugs and request features
Discussions: Ask questions and share ideas
Pull Requests: Submit your contributions

Thank You!

Thank you for contributing and helping to maintain the quality and consistency of the project! Every contribution, no matter how small, makes a difference! 🙏✨

Navigation Menu

Uh oh!

🤝 Contribution Guidelines

🌟 New to Contributing? Start Here!

🏷️ Issue Labels Explained

🌿 Branching Strategy

💬 Commit Messages

🛠️ Development Environment

🐳 Using the Dev Container (Highly Recommended!)

📋 Prerequisites

🚀 Getting Started

🎮 Development Workflow

🔗 Connecting to a Spoolman Instance

🐛 Debugging

📁 Folder Structure

🔄 Updating Home Assistant in Dev Container

💡 Tips & Tricks

🏠 Alternative: Local Development (Without Container)

CI/CD Requirements

General Guidelines

🎖️ Recognition

🤖 Automated Workflows

📚 Additional Resources

💬 Community

Thank You!

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

🤝 Contribution Guidelines

🌟 New to Contributing? Start Here!

🏷️ Issue Labels Explained

🌿 Branching Strategy

💬 Commit Messages

🛠️ Development Environment

🐳 Using the Dev Container (Highly Recommended!)

📋 Prerequisites

🚀 Getting Started

🎮 Development Workflow

🔗 Connecting to a Spoolman Instance

🐛 Debugging

📁 Folder Structure

🔄 Updating Home Assistant in Dev Container

💡 Tips & Tricks

🏠 Alternative: Local Development (Without Container)

CI/CD Requirements

General Guidelines

🎖️ Recognition

🤖 Automated Workflows

📚 Additional Resources

💬 Community

Thank You!