docs: consolidate development and contribution guides to reduce duplication #61
Conversation
|
Thanks Travis! In the 105 days since first releasing VoiceMode it's had 859 commits and 95 releases. The docs got big and outdated so I did a massive cull and rewrite but added notes that they need review. I've been focused on other things (testing install scripts on fresh OS installs, new features, my day job, etc) so really appreciate you putting the time into docs). I did a quick review and overall it looks good. There is the "mcp" command in there that I've never heard of. I've been using "voicemode converse" as a really powerful way to test and see what's going on. I'll need to find some time to review but appreciate you pushing it forward a bit. |
docs/tutorials/development-setup.md
Outdated
| uv run pytest | ||
|
|
||
| # Method 3: Using the Makefile | ||
| make test |
There was a problem hiding this comment.
Any reason to put make test last?
There was a problem hiding this comment.
No. I just interpred that would be your preference based on when I think the Makefile was added to the project. (My personal preference is Makefile's should be the entry to all things.) Lets move it up to the top!
There was a problem hiding this comment.
Updated in commit 4573d25. make test and make commands in general are the primary recommendation.
There was a problem hiding this comment.
Hi @mbailey want any more changes? I can resolve these conversations if you like.
| cd voicemode | ||
|
|
||
| # Install in development mode | ||
| uv tool install -e . |
There was a problem hiding this comment.
Why do you prefer this over uv tool install -e .?
There was a problem hiding this comment.
I don't necessarily. (My end goal here was to figure out a particular bug I am having in Livekit and submit a fix. But I had a tough time figuring out best practices on the dev environment.) So I merged from several docs, to come up with this. If uv tool install -e . is best practice, lets go with that.
There was a problem hiding this comment.
actually, Yes, if you want to have a virtual environment we need the uv venv and activate line. Because this is development mode, we should keep use the uv pip install -e .[dev,test] and drop the uv pip install -e .
There was a problem hiding this comment.
uv tool install
- creates a self contained venv
- puts all scripts in your path
docs/tutorials/development-setup.md
Outdated
| ## Contributing | ||
| 2. **Run `mcp` to test the connection** | ||
| ```bash | ||
| mcp test voice-mode |
There was a problem hiding this comment.
Bad AI recommendation that I forgot to get rid of. New commit comming.
|
I haven't forgotten this but my personal time has been focussed on other issues (replaced install.sh with Are you using VoiceMode with Livekit? |
|
I was starting to look into live kit but other stuff unfortunately is taking my time. |
…cation - Update development-setup.md with correct uv workflow - Replace `uv tool install -e .` with proper venv creation steps - Replace `uv add --dev pytest` with `uv pip install -e .[dev,test]` - Add virtual environment activation steps - Document multiple methods to run pytest - Reorganize content between guides - Move code style, commit conventions, and PR process to CONTRIBUTING.md - Add comprehensive contribution workflow section to CONTRIBUTING.md - Replace duplicated sections with cross-references - Establish clear document purposes - CONTRIBUTING.md: contribution workflow, conventions, and process - development-setup.md: technical setup, environment, and tools - Each document now has a distinct focus area - Enhance developer experience - Add troubleshooting section for common pytest issues - Document pyenv/VIRTUAL_ENV conflict resolution - Include verification steps for installation This simplifies the documentation by consolidating related information and removing duplication, making it easier for contributors to navigate and find the information they need.
- Make `make dev-install` the primary recommended setup method - Add new section on testing service installations in temp directories - Consolidate Makefile commands reference for better discoverability - Emphasize `make help` for comprehensive target list - Add VOICEMODE_BASE_DIR override example for isolated testing - Brought back the more efficient `uv tool install` instead of sourcing .venv
x85446
force-pushed
the
docs/consolidate-development-docs
branch
from
0804ef2 to
b6fa7c6
Compare
2 participants
Summary
Thank you for maintaining this excellent voice interaction tool! This PR streamlines the documentation by consolidating related content and reducing duplication between the development and contribution guides.
Changes
uvworkflow with proper virtual environment steps and added troubleshooting sectionBenefits
Testing
Verified all commands work as documented, including the various ways to run pytest.
This follows the project's conventional commit format. Happy to make any adjustments you'd like!