diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 000000000..743a4b3a3 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,3 @@ +# These are supported funding model platforms + +github: maziggy diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..9870c330f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,46 @@ +# Code of Conduct + +## Our Commitment + +The Bambuddy community is dedicated to providing a welcoming and supportive environment for everyone. We value respectful collaboration and constructive dialogue. + +## Expected Behavior + +- **Be Respectful**: Treat others with kindness and consideration. Disagreements are fine; personal attacks are not. +- **Be Inclusive**: Welcome people of all backgrounds and experience levels. Avoid exclusionary language or behavior. +- **Be Constructive**: Offer helpful feedback. Focus on ideas, not individuals. +- **Be Patient**: Remember that contributors have varying levels of experience and availability. + +## Unacceptable Behavior + +- Harassment, insults, or discriminatory remarks +- Personal attacks or inflammatory comments +- Publishing others' private information without consent +- Trolling or deliberately disruptive behavior +- Any conduct that would be inappropriate in a professional setting + +## Reporting Issues + +If you experience or witness unacceptable behavior: + +1. **Contact the maintainers** via email or GitHub +2. **Provide details** about what happened and when +3. **All reports will be handled confidentially** + +We will review and respond to all reports promptly. + +## Enforcement + +Maintainers may take any action they deem appropriate, including: + +- Requesting a change in behavior +- Temporary or permanent bans from community spaces +- Removal of contributions that violate this code + +## Scope + +This code of conduct applies to all Bambuddy community spaces, including GitHub issues, pull requests, discussions, and any other communication channels. + +--- + +Thank you for helping make Bambuddy a welcoming community! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..3872110b5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,224 @@ +# Contributing to Bambuddy + +Thank you for your interest in contributing to Bambuddy! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Making Changes](#making-changes) +- [Code Style](#code-style) +- [Testing](#testing) +- [Submitting Changes](#submitting-changes) +- [Reporting Bugs](#reporting-bugs) +- [Requesting Features](#requesting-features) + +## Code of Conduct + +Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) to keep our community welcoming and respectful. + +## Getting Started + +1. **Fork the repository** on GitHub +2. **Clone your fork** locally: + ```bash + git clone https://github.com/YOUR_USERNAME/bambuddy.git + cd bambuddy + ``` +3. **Add the upstream remote**: + ```bash + git remote add upstream https://github.com/maziggy/bambuddy.git + ``` + +## Development Setup + +### Prerequisites + +- Python 3.10+ (3.11/3.12 recommended) +- Node.js 18+ +- npm or yarn + +### Backend Setup + +```bash +# Create virtual environment +python3 -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate + +# Install dependencies +pip install -r requirements.txt + +# Install pre-commit hooks +pip install pre-commit +pre-commit install + +# Run backend +DEBUG=true uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000 +``` + +### Frontend Setup + +```bash +cd frontend + +# Install dependencies +npm install + +# Run development server +npm run dev +``` + +The frontend will be available at `http://localhost:5173` and will proxy API requests to the backend. + +### Running with Docker + +```bash +docker compose up -d --build +``` + +## Making Changes + +1. **Create a branch** for your changes: + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b fix/your-bug-fix + ``` + +2. **Make your changes** following our code style guidelines + +3. **Test your changes** thoroughly + +4. **Commit your changes** with clear, descriptive messages: + ```bash + git commit -m "Add feature: description of what you added" + ``` + +### Branch Naming + +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation changes +- `refactor/` - Code refactoring +- `test/` - Test additions or fixes + +## Code Style + +### Backend (Python) + +We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting: + +```bash +# Check linting +ruff check . + +# Auto-fix issues +ruff check --fix . + +# Format code +ruff format . +``` + +### Frontend (TypeScript/React) + +We use ESLint and Prettier: + +```bash +cd frontend + +# Lint +npm run lint + +# Type check +npm run type-check +``` + +### Pre-commit Hooks + +Pre-commit hooks run automatically on `git commit`. To run manually: + +```bash +pre-commit run --all-files +``` + +## Testing + +### Backend Tests + +```bash +# Run all tests +pytest + +# Run with coverage +pytest --cov=backend + +# Run specific test file +pytest backend/app/tests/test_example.py +``` + +### Frontend Tests + +```bash +cd frontend + +# Run tests +npm test + +# Run with coverage +npm run test:coverage +``` + +## Submitting Changes + +1. **Push your branch** to your fork: + ```bash + git push origin feature/your-feature-name + ``` + +2. **Create a Pull Request** on GitHub: + - Use a clear, descriptive title + - Fill out the PR template completely + - Link any related issues + - Include screenshots for UI changes + +3. **Wait for review** - maintainers will review your PR and may request changes + +### PR Guidelines + +- Keep PRs focused and reasonably sized +- One feature or fix per PR +- Update documentation if needed +- Add tests for new functionality +- Ensure all tests pass +- Follow the existing code style + +## Reporting Bugs + +Use the [Bug Report template](https://github.com/maziggy/bambuddy/issues/new?template=bug_report.yml) and include: + +- Clear description of the bug +- Steps to reproduce +- Expected vs actual behavior +- Your environment (OS, Python version, browser) +- Printer model and firmware version +- Relevant logs + +## Requesting Features + +Use the [Feature Request template](https://github.com/maziggy/bambuddy/issues/new?template=feature_request.yml) and include: + +- Clear description of the feature +- Use case / problem it solves +- Proposed solution +- Alternatives considered + +## Questions? + +- Check the [Documentation](http://wiki.bambuddy.cool) +- Open a [Discussion](https://github.com/maziggy/bambuddy/discussions) +- Review existing [Issues](https://github.com/maziggy/bambuddy/issues) + +--- + +Thank you for contributing to Bambuddy! diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..4fba9d6cc --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,96 @@ +# Security Policy + +## Reporting a Vulnerability + +The Bambuddy team takes security seriously. We appreciate your efforts to responsibly disclose your findings. + +### How to Report + +**Please DO NOT report security vulnerabilities through public GitHub issues.** + +Instead, please report them via email to: + +**security@bambuddy.cool** + +Or use GitHub's private vulnerability reporting feature: +1. Go to the [Security tab](https://github.com/maziggy/bambuddy/security) +2. Click "Report a vulnerability" +3. Fill out the form with details + +### What to Include + +Please include the following information in your report: + +- **Description** of the vulnerability +- **Steps to reproduce** the issue +- **Affected versions** of Bambuddy +- **Potential impact** of the vulnerability +- **Any suggested fixes** (if you have them) + +### What to Expect + +- **Acknowledgment**: We will acknowledge receipt of your report within 48 hours +- **Assessment**: We will investigate and validate the issue within 7 days +- **Updates**: We will keep you informed of our progress +- **Resolution**: We aim to release a fix within 30 days for critical issues +- **Credit**: We will credit you in our release notes (unless you prefer to remain anonymous) + +## Supported Versions + +| Version | Supported | +| ------- | ------------------ | +| 0.1.x | :white_check_mark: | + +## Security Considerations + +### Network Security + +Bambuddy communicates with your printers over your local network using: + +- **MQTT over TLS** (port 8883) - Encrypted printer communication +- **FTPS** (port 990) - Encrypted file transfers + +### Recommendations + +1. **Run on trusted network**: Bambuddy should only be accessible on your local network +2. **Use reverse proxy**: If exposing to the internet, use a reverse proxy with HTTPS +3. **Keep updated**: Always run the latest version for security patches +4. **Secure API keys**: Treat API keys like passwords; don't share them publicly +5. **LAN Mode**: Use your printer's LAN Mode access code; don't share it + +### Known Security Features + +- API key authentication for external access +- No default credentials +- Local-only by default (no cloud dependency) +- TLS encryption for printer communication + +## Scope + +The following are **in scope** for security reports: + +- Authentication/authorization bypasses +- Remote code execution +- SQL injection +- Cross-site scripting (XSS) +- Cross-site request forgery (CSRF) +- Sensitive data exposure +- Insecure direct object references + +The following are **out of scope**: + +- Issues in dependencies (report to the upstream project) +- Social engineering attacks +- Physical attacks +- Denial of service (DoS) attacks +- Issues requiring physical access to the server + +## Acknowledgments + +We thank the following individuals for responsibly disclosing security issues: + +*No security issues have been reported yet.* + +--- + +Thank you for helping keep Bambuddy and its users safe!