vitesse-dependency-scripts/CONTRIBUTING.md

Automated toolkit for managing dependencies with pnpm catalogs in Vue/Vite projects

# Contributing to Vitesse Dependency Scripts

Thank you for your interest in contributing! This guide will help you get started.

## 🚀 Getting Started

1. **Clone the repository**
   ```bash
   git clone <your-repo-url> dependency-scripts
   cd dependency-scripts
   ```

2. **Make scripts executable**
   ```bash
   chmod +x *.js *.sh
   ```

3. **Test your changes**
   ```bash
   # Test project creation
   node create-project-instant.js test-project
   
   # Test updates (from a project with pnpm-workspace.yaml)
   cd ../some-vitesse-project
   node ../dependency-scripts/auto-update-full.js
   ```

## 📝 Development Guidelines

### Code Style

- Use ES modules (`import`/`export`)
- Use camelCase for variables and functions
- Add JSDoc comments for functions
- Use colored console output for better UX
- Always include error handling

### File Structure

- **Scripts** (*.js): Executable Node.js scripts with shebang `#!/usr/bin/env node`
- **Documentation** (*.md): Comprehensive guides and references
- **Config** (*.yaml, *.json): Configuration and reference files

### Adding New Dependencies

When adding packages to the managed list:

1. Update all three script files:
   - `create-project-instant.js`
   - `create-vitesse-project.js`
   - `auto-update-full.js`
   - `auto-update-catalog.js`

2. Update the catalog structure in `catalog-additions.yaml`

3. Update `MISSING_DEPENDENCIES.md` with descriptions

4. Test with a fresh project creation

### Testing Changes

Before submitting changes:

1. **Test project creation**
   ```bash
   node create-project-instant.js test-app
   cd test-app
   pnpm dev
   ```

2. **Test updates**
   ```bash
   cd existing-vitesse-project
   node ../dependency-scripts/auto-update-full.js
   pnpm install
   ```

3. **Verify documentation**
   - Check that all README files are up to date
   - Ensure examples work as documented
   - Update version numbers if needed

## 🐛 Reporting Issues

When reporting issues, please include:

- Node.js version (`node --version`)
- pnpm version (`pnpm --version`)
- Operating system
- Steps to reproduce
- Expected vs actual behavior
- Error messages/logs

## 💡 Feature Requests

Have an idea? Great! Please:

1. Check if it already exists in issues
2. Describe the problem it solves
3. Provide example use cases
4. Consider backward compatibility

## 🔄 Pull Request Process

1. **Fork and create a branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes**
   - Write clear commit messages
   - Update documentation
   - Add tests if applicable

3. **Test thoroughly**
   - Test all affected scripts
   - Verify documentation accuracy
   - Check for breaking changes

4. **Submit PR**
   - Describe what changed and why
   - Reference any related issues
   - Include testing steps

## 📚 Documentation

When updating docs:

- Keep language simple and clear
- Include code examples
- Use emojis for visual clarity
- Update the main README.md
- Cross-reference related docs

## ✅ Checklist

Before submitting:

- [ ] Code follows project style
- [ ] All scripts are executable
- [ ] Documentation is updated
- [ ] Examples are tested
- [ ] No breaking changes (or clearly documented)
- [ ] Error handling is included
- [ ] Console output is helpful and colored

## 🎯 Areas to Contribute

- **New package support**: Add more commonly used packages
- **Better error handling**: Improve error messages and recovery
- **Performance**: Optimize package version fetching
- **Documentation**: More examples and guides
- **Testing**: Add automated tests
- **CI/CD**: GitHub Actions for testing
- **Interactive mode**: Add prompts for package selection

## 📞 Questions?

- Check existing documentation first
- Look at similar issues/PRs
- Create a discussion for general questions
- File an issue for bugs

---

Thank you for contributing! 🎉