docs: improve project documentation for a clearer public surface (#634)
* docs: polish project documentation for a clearer public surface Rewrite the README and supporting docs for a more professional first impression: less emoji and badge noise, install-first structure, and a real documentation index. Add a Contributor Covenant, tighten SECURITY and GitHub templates, and make distro/update guides read as product docs instead of internal status notes. * docs: split install guide and add changelog plus support pages Break INSTALL.md into a short primary guide, manual/PyPI package lists, and troubleshooting. Add root CHANGELOG.md and SUPPORT.md, wire them into the docs index and README, and drop the outdated screenshot lag note now that v0.15 assets are on main. * docs: humanize PR copy and remove em dashes Strip em/en dashes from the documentation rewritten in this PR, fix mid-sentence colon fallout from that pass, and smooth a few stiff phrases so the public docs read more natural. * docs: list Faster Whisper after rebase onto main Installer and CLI already accept faster_whisper. Document it next to the other engines, drop the outdated screenshot lag note, and keep the on-device wording honest for local vs remote.
This commit is contained in:
@@ -1,42 +1,52 @@
|
||||
---
|
||||
name: Bug Report
|
||||
about: Report a bug to help us improve Vocalinux
|
||||
about: Report a bug to help improve Vocalinux
|
||||
title: "[BUG] "
|
||||
labels: bug
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
## 🐛 Bug Description
|
||||
A clear and concise description of what the bug is.
|
||||
## Bug description
|
||||
|
||||
## 📋 Steps to Reproduce
|
||||
1. Go to '...'
|
||||
2. Click on '...'
|
||||
3. Speak '...'
|
||||
4. See error
|
||||
A clear description of what went wrong.
|
||||
|
||||
## ✅ Expected Behavior
|
||||
A clear and concise description of what you expected to happen.
|
||||
## Steps to reproduce
|
||||
|
||||
## ❌ Actual Behavior
|
||||
What actually happened.
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
## 📸 Screenshots
|
||||
If applicable, add screenshots to help explain your problem.
|
||||
## Expected behavior
|
||||
|
||||
## 💻 Environment
|
||||
- **OS**: [e.g., Ubuntu 24.04]
|
||||
- **Python Version**: [e.g., 3.12]
|
||||
- **Vocalinux Version**: [e.g., 0.2.0-alpha]
|
||||
- **Display Server**: [X11 / Wayland]
|
||||
- **Speech Engine**: [VOSK / Whisper]
|
||||
- **Model Size**: [small / medium / large]
|
||||
What you expected to happen.
|
||||
|
||||
## Actual behavior
|
||||
|
||||
What happened instead.
|
||||
|
||||
## Screenshots
|
||||
|
||||
If applicable, attach screenshots.
|
||||
|
||||
## Environment
|
||||
|
||||
- **OS / distro**: (e.g. Ubuntu 24.04)
|
||||
- **Python version**: (e.g. 3.12; 3.11+ required)
|
||||
- **Vocalinux version**: (`vocalinux --version`)
|
||||
- **Install method**: (installer / AppImage / AUR / Flatpak / Snap / source / PyPI)
|
||||
- **Display server**: (X11 / Wayland)
|
||||
- **Desktop environment**: (e.g. GNOME, KDE Plasma)
|
||||
- **Speech engine**: (whisper_cpp / whisper / vosk / parakeet / remote_api)
|
||||
- **Model**: (e.g. tiny, medium.en-q5_0, v3-european)
|
||||
|
||||
## Debug logs
|
||||
|
||||
Run `vocalinux --debug` and paste the relevant output:
|
||||
|
||||
## 📋 Debug Logs
|
||||
Run `vocalinux --debug` and paste relevant log output:
|
||||
```
|
||||
[paste logs here]
|
||||
```
|
||||
|
||||
## 📝 Additional Context
|
||||
Add any other context about the problem here.
|
||||
## Additional context
|
||||
|
||||
Anything else that might help (recent upgrade, Bluetooth mic, multi-GPU, etc.).
|
||||
|
||||
@@ -6,26 +6,27 @@ labels: enhancement
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
## 🚀 Feature Description
|
||||
A clear and concise description of the feature you'd like.
|
||||
## Feature description
|
||||
|
||||
## 💡 Problem Statement
|
||||
Is your feature request related to a problem? Please describe.
|
||||
Example: "I'm always frustrated when [...]"
|
||||
What you would like Vocalinux to do.
|
||||
|
||||
## 📋 Proposed Solution
|
||||
Describe the solution you'd like. Be as detailed as possible.
|
||||
## Problem
|
||||
|
||||
## 🔄 Alternatives Considered
|
||||
Describe any alternative solutions or features you've considered.
|
||||
What is hard or missing today? Who is affected?
|
||||
|
||||
## 📸 Mockups / Examples
|
||||
If applicable, add mockups, screenshots, or examples from other applications.
|
||||
## Proposed solution
|
||||
|
||||
## 📝 Additional Context
|
||||
Add any other context about the feature request here.
|
||||
How you imagine it working (as specific as you can).
|
||||
|
||||
## ✅ Acceptance Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
- [ ] Criterion 3
|
||||
## Alternatives considered
|
||||
|
||||
Other approaches or tools you already tried.
|
||||
|
||||
## Mockups / examples
|
||||
|
||||
Links, screenshots, or references to similar apps (optional).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
@@ -1,33 +1,34 @@
|
||||
## Description
|
||||
|
||||
<!-- Describe your changes in detail -->
|
||||
<!-- What changed and why. Link design docs or discussions if relevant. -->
|
||||
|
||||
## Related Issue
|
||||
## Related issue
|
||||
|
||||
<!-- Link to the related issue if applicable -->
|
||||
<!-- Link the issue this closes, if any. -->
|
||||
Fixes #
|
||||
|
||||
## Type of Change
|
||||
## 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 change)
|
||||
- [ ] 📖 Documentation update
|
||||
- [ ] 🧹 Code refactoring
|
||||
- [ ] ✅ Test update
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Breaking change
|
||||
- [ ] Documentation
|
||||
- [ ] Refactor
|
||||
- [ ] Tests
|
||||
- [ ] Packaging / CI
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] My code follows the code style of this project (black, isort)
|
||||
- [ ] I have updated the documentation accordingly
|
||||
- [ ] I have added tests to cover my changes
|
||||
- [ ] All new and existing tests pass locally
|
||||
- [ ] Pre-commit hooks pass
|
||||
- [ ] Code follows project style (Black, isort, flake8)
|
||||
- [ ] Documentation updated when user-facing behavior or install steps change
|
||||
- [ ] Tests added or updated for the change
|
||||
- [ ] Local tests pass (`pytest`)
|
||||
- [ ] Conventional commit message style
|
||||
|
||||
## Screenshots (if applicable)
|
||||
|
||||
<!-- Add screenshots to help explain your changes -->
|
||||
<!-- UI changes: before/after if helpful -->
|
||||
|
||||
## Additional Notes
|
||||
## Notes for reviewers
|
||||
|
||||
<!-- Add any additional notes for reviewers -->
|
||||
<!-- Anything not obvious from the diff -->
|
||||
|
||||
Reference in New Issue
Block a user