docs: improve docs

.cursor/rules/changelog-best-practices.mdc

@@ -0,0 +1,156 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Changelog Best Practices
+
+All contributors must update `CHANGELOG.md` when creating PRs. Follow these guidelines to ensure consistent and useful changelog entries.
+
+## General Principles
+
+- Changelogs are for humans, not machines
+- Include an entry for every version, with the latest first
+- Group similar changes under appropriate categories: Added, Changed, Improved, Deprecated, Removed, Fixed, Documentation, Performance, CI
+- **"Test" is NOT a valid changelog category** - tests should be mentioned within the related feature or fix entry, not as standalone entries
+- Use an "Unreleased" section for upcoming changes
+- Follow Semantic Versioning where possible
+- Use ISO 8601 date format: YYYY-MM-DD
+- Avoid dumping raw git logs; summarize notable changes clearly
+
+## Required Actions
+
+1. **Add entries to the `[Unreleased]` section** - Add your changes under the appropriate category
+2. **Follow the changelog format** - See examples in `CHANGELOG.md` for detailed guidelines
+3. **Group related changes** - Similar changes should be grouped together
+4. **Be descriptive** - Write clear, user-focused descriptions of what changed
+5. **Mention tests when relevant** - Tests should be mentioned within the related feature or fix entry, not as standalone entries
+
+## Categories
+
+### Added
+- New features, endpoints, functionality
+- New dependencies or integrations
+- New configuration options
+
+### Changed
+- Changes to existing functionality
+- API changes (non-breaking)
+- Dependency updates
+- Configuration changes
+
+### Fixed
+- Bug fixes
+- Security fixes
+- Error handling improvements
+
+### Documentation
+- Documentation additions or updates
+- README changes
+- Contributing guide updates
+- Code comments and docstrings (only if significant)
+
+### Performance
+- Performance improvements
+- Optimization changes
+- Caching improvements
+
+### CI
+- CI/CD pipeline changes
+- GitHub Actions workflow updates
+- Automation improvements
+- Branch protection rules
+
+### Deprecated
+- Features marked for removal
+- Deprecated API endpoints
+
+### Removed
+- Removed features or functionality
+- Removed dependencies
+
+## Format Guidelines
+
+### Entry Structure
+
+```markdown
+- **Component/Feature Name**: Brief description of the change
+  - Additional details or sub-features
+  - Test coverage information (if relevant)
+```
+
+### Examples
+
+**Good Examples:**
+
+```markdown
+### Added
+
+- **Track API**: Added batch upload endpoint for multiple tracks
+  - Includes comprehensive unit tests covering various file formats and error scenarios
+  - Supports parallel upload processing for improved performance
+
+### Fixed
+
+- **Track Upload**: Fixed issue with handling large audio files exceeding size limits
+  - Includes regression tests to prevent future occurrences
+  - Improved error messages for better user feedback
+
+### Documentation
+
+- **Contributing Guide**: Added comprehensive Git Flow workflow documentation
+  - Includes branch naming conventions and merging rules
+  - Added pre-PR checklist and review process guidelines
+
+### CI
+
+- **Branch Protection**: Added automated enforcement of Git Flow branching rules
+  - Blocks invalid PRs to main and develop branches
+```
+
+**Bad Examples:**
+
+```markdown
+# Bad - Too vague
+- Fixed bug
+
+# Bad - Test as standalone entry
+### Test
+- Added tests for track upload
+
+# Bad - Raw git log style
+- commit abc123: update dependencies
+
+# Bad - Wrong category
+### Added
+- Updated README.md (should be Documentation)
+```
+
+## Documentation Entries
+
+Documentation changes should be grouped under the **Documentation** category, not under Added or Changed. This includes:
+
+- README updates
+- Contributing guide changes
+- Development guidelines
+- API documentation
+- Code comments (only if significant additions)
+- Documentation infrastructure setup
+
+## Release Process
+
+During releases, maintainers will:
+1. Move entries from `[Unreleased]` to a versioned section (e.g., `## [v0.2.8] - 2025-01-15`)
+2. Review and consolidate related entries
+3. Ensure all entries follow the format guidelines
+4. Update version numbers and dates
+
+## Checklist
+
+Before submitting a PR, ensure:
+- ✅ All changes are documented in `CHANGELOG.md` under `[Unreleased]`
+- ✅ Entries are in the correct category
+- ✅ Entries follow the format guidelines
+- ✅ Tests are mentioned within related entries (not as standalone entries)
+- ✅ Documentation changes are in the Documentation category
+- ✅ Entries are clear and user-focused

.github/DISCUSSIONS/discussion-body-template.md

@@ -0,0 +1,138 @@
+# Discussion Body Template
+
+This is a template you can copy when creating new discussions. Choose the appropriate section based on your discussion type.
+
+---
+
+## For Questions (Q&A)
+
+**Question:**
+[Your question here]
+
+**Context:**
+
+- What are you trying to achieve?
+- What have you already tried?
+- What's your current setup?
+
+**Environment:**
+
+- Docker version: [e.g., 24.0.0]
+- Postgres version: [e.g., 16.4]
+- OS: [e.g., macOS, Linux, Windows]
+
+**Error Messages/Logs (if applicable):**
+
+```
+[Paste error messages or logs here]
+```
+
+**Additional Information:**
+[Any other relevant details]
+
+---
+
+## For Ideas
+
+**Idea:**
+[Brief description of your idea]
+
+**Problem Statement:**
+[What problem does this solve?]
+
+**Proposed Solution:**
+[How would this work?]
+
+**Use Cases:**
+
+1. [Use case 1]
+2. [Use case 2]
+3. [Use case 3]
+
+**Alternatives Considered:**
+[What other approaches did you consider?]
+
+**Priority:**
+[ ] Nice to have
+[ ] Would be helpful
+[ ] Important
+[ ] Critical
+
+**Additional Context:**
+[Any mockups, examples, or additional information]
+
+---
+
+## For Show & Tell
+
+**Project Name:**
+[Name of your project/integration]
+
+**Description:**
+[What you've built or how you're using Bodzify DB Postgres]
+
+**Key Features:**
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+**Screenshots/Demo:**
+[Add images or links here]
+
+**Lessons Learned:**
+[What did you learn? What worked well?]
+
+**Feedback:**
+[Any feedback about the project or suggestions for improvement]
+
+**Links:**
+
+- Repository: [link]
+- Demo: [link]
+- Documentation: [link]
+
+---
+
+## For General Discussion
+
+**Topic:**
+[What you'd like to discuss]
+
+**Context:**
+[Background information]
+
+**Discussion Points:**
+
+1. [Point 1]
+2. [Point 2]
+3. [Point 3]
+
+**Questions for the Community:**
+[What would you like input on?]
+
+---
+
+## Tips for Better Discussions
+
+1. **Use Clear Titles** - Make your title descriptive and specific
+2. **Provide Context** - Include relevant background information
+3. **Use Code Blocks** - Format code snippets properly
+4. **Include Examples** - Show what you've tried or what you're looking for
+5. **Be Patient** - Give the community time to respond
+6. **Follow Up** - Update your discussion if you find a solution
+7. **Mark as Answered** - Help others by marking helpful responses
+
+---
+
+## Formatting Help
+
+- Use `backticks` for inline code
+- Use triple backticks for code blocks:
+  ```python
+  # Your code here
+  ```
+- Use `-` or `*` for bullet points
+- Use `##` for section headers
+- Use `**bold**` for emphasis
+- Use `[link text](url)` for links

.github/DISCUSSIONS/ideas.yml

@@ -0,0 +1,68 @@
+title: "[Idea]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for sharing your idea! This helps us understand what features would be valuable to the community.
+
+  - type: textarea
+    id: idea-description
+    attributes:
+      label: Idea Description
+      description: Describe your idea in detail
+      placeholder: What would you like to see added or improved?
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this idea solve?
+      placeholder: This would help with...
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-cases
+    attributes:
+      label: Use Cases
+      description: Describe specific scenarios where this would be useful
+      placeholder: |
+        1. Use case 1: ...
+        2. Use case 2: ...
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative approaches?
+      placeholder: I also thought about...
+    validations:
+      required: false
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: How important is this to you?
+      options:
+        - Nice to have
+        - Would be helpful
+        - Important
+        - Critical
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other context, mockups, or examples
+      placeholder: Add any other context here...
+    validations:
+      required: false
+