feat: project refactoring - folder cleanup, governance, and automation
Project Structure Cleanup: - Remove deprecated cmdb-assistant plugin - Remove development output files (test scripts, status reports) - Remove IDE-specific workspace files - Create scripts/ directory for automation - Create docs/architecture/ for Draw.io diagrams - Create docs/workflows/ for workflow documentation - Create .scratch/ directory for transient work Governance & Documentation: - Add File Creation Governance section to CLAUDE.md - Add architecture diagram specifications (component-map, agent-workflow) - Add docs/UPDATING.md with update workflow - Update CHANGELOG.md with all changes Installation Automation: - Add scripts/setup.sh for initial installation - Add scripts/post-update.sh for updates after git pull - Add /initial-setup slash command Maintenance: - Update .gitignore with scratch directory - Fix all project name references (use support-claude-mktplace) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
101
docs/UPDATING.md
Normal file
101
docs/UPDATING.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Updating support-claude-mktplace
|
||||
|
||||
This guide covers how to update your local installation when new versions are released.
|
||||
|
||||
## Quick Update
|
||||
|
||||
```bash
|
||||
# 1. Pull latest changes
|
||||
cd /path/to/support-claude-mktplace
|
||||
git pull origin main
|
||||
|
||||
# 2. Run post-update script
|
||||
./scripts/post-update.sh
|
||||
```
|
||||
|
||||
## What the Post-Update Script Does
|
||||
|
||||
1. **Updates Python dependencies** for Gitea and Wiki.js MCP servers
|
||||
2. **Shows recent changelog entries** so you know what changed
|
||||
3. **Validates your configuration** is still compatible
|
||||
|
||||
## Manual Steps After Update
|
||||
|
||||
Some updates may require manual configuration changes:
|
||||
|
||||
### New Environment Variables
|
||||
|
||||
If the changelog mentions new environment variables:
|
||||
|
||||
1. Check the variable name and purpose in the changelog
|
||||
2. Add it to the appropriate config file:
|
||||
- Gitea variables → `~/.config/claude/gitea.env`
|
||||
- Wiki.js variables → `~/.config/claude/wikijs.env`
|
||||
- Project variables → `.env` in your project root
|
||||
|
||||
### New MCP Server Features
|
||||
|
||||
If a new MCP server tool is added:
|
||||
|
||||
1. The post-update script handles dependency installation
|
||||
2. Check `docs/references/MCP-*.md` for usage documentation
|
||||
3. New tools are available immediately after update
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
Breaking changes will be clearly marked in CHANGELOG.md with migration instructions.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Dependencies fail to install
|
||||
|
||||
```bash
|
||||
# Rebuild virtual environment
|
||||
cd mcp-servers/gitea
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
deactivate
|
||||
|
||||
# Repeat for wikijs
|
||||
cd ../wikijs
|
||||
rm -rf .venv
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
deactivate
|
||||
```
|
||||
|
||||
### Configuration no longer works
|
||||
|
||||
1. Check CHANGELOG.md for breaking changes
|
||||
2. Compare your config files with updated `.env.example` (if provided)
|
||||
3. Run `./scripts/setup.sh` to validate configuration
|
||||
|
||||
### MCP server won't start
|
||||
|
||||
1. Check Python version: `python3 --version` (requires 3.10+)
|
||||
2. Verify venv exists: `ls mcp-servers/gitea/.venv`
|
||||
3. Check logs for specific errors
|
||||
|
||||
## Version Pinning
|
||||
|
||||
To stay on a specific version:
|
||||
|
||||
```bash
|
||||
# List available tags
|
||||
git tag
|
||||
|
||||
# Checkout specific version
|
||||
git checkout v1.0.0
|
||||
|
||||
# Run post-update
|
||||
./scripts/post-update.sh
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Check `docs/references/` for component documentation
|
||||
- Review CHANGELOG.md for recent changes
|
||||
- Search existing issues in Gitea
|
||||
Reference in New Issue
Block a user