vibe-seo/CONTRIBUTING.md

AI-friendly SEO generator for modern web frameworks

# Contributing to vibe-seo

Thank you for considering contributing to vibe-seo! We welcome contributions from the community and are excited to see what you'll build.

## 🚀 Getting Started

### Development Setup

1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
   ```bash
   git clone https://github.com/YOUR_USERNAME/vibe-seo.git
   cd vibe-seo
   ```

3. **Install dependencies**:
   ```bash
   npm install
   ```

4. **Link for local development**:
   ```bash
   npm link
   ```

5. **Test the installation**:
   ```bash
   vibe-seo-init --help
   vibe-seo-gen --help
   ```

### Project Structure

```
vibe-seo/
├── bin/                     # CLI executables
│   ├── vibe-seo-init.js    # Initialization command
│   └── vibe-seo-gen.js     # Generation command
├── lib/                     # Core library
│   ├── index.js            # Main exports
│   ├── config.js           # Configuration management
│   ├── utils.js            # Utility functions
│   └── generators/         # File generators
├── templates/              # Template files
├── docs/                   # Documentation
└── __tests__/              # Test files
```

## 🐛 Reporting Issues

When reporting issues, please include:

1. **Environment Information**:
   - Node.js version
   - npm version
   - Operating system
   - Framework being used (Next.js, React, etc.)

2. **Steps to Reproduce**:
   - Clear, step-by-step instructions
   - Expected vs actual behavior
   - Any relevant configuration files

3. **Context**:
   - What you were trying to achieve
   - Any error messages or logs
   - Screenshots if applicable

## 💡 Feature Requests

We love feature requests! Please:

1. **Check existing issues** to avoid duplicates
2. **Describe the use case** clearly
3. **Explain the benefits** to other users
4. **Consider implementation complexity**

## 🔧 Development Guidelines

### Code Style

- Use **ES6+ features** where appropriate
- Follow **consistent naming conventions**
- Add **JSDoc comments** for functions
- Keep functions **small and focused**
- Use **async/await** for asynchronous operations

### Framework Support

When adding support for new frameworks:

1. **Add detection logic** in `lib/utils.js`
2. **Implement page scanning** for the framework
3. **Add configuration defaults** in `lib/config.js`
4. **Update documentation** and examples
5. **Add tests** for the new functionality

### Testing

- Write tests for new features
- Ensure existing tests pass
- Test with multiple frameworks
- Test CLI commands end-to-end

### Documentation

- Update README.md for new features
- Add JSDoc comments for new functions
- Include examples in documentation
- Update CLI help text if needed

## 📝 Pull Request Process

1. **Create a feature branch**:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes**:
   - Follow the development guidelines
   - Add tests for new functionality
   - Update documentation as needed

3. **Test your changes**:
   ```bash
   npm test
   npm run lint
   ```

4. **Commit your changes**:
   ```bash
   git add .
   git commit -m "feat: add your feature description"
   ```

5. **Push to your fork**:
   ```bash
   git push origin feature/your-feature-name
   ```

6. **Create a pull request**:
   - Use a descriptive title
   - Explain what changes you made
   - Reference any related issues
   - Include screenshots if applicable

### Commit Message Convention

We use conventional commits:

- `feat:` - New features
- `fix:` - Bug fixes
- `docs:` - Documentation changes
- `style:` - Code style changes
- `refactor:` - Code refactoring
- `test:` - Adding or updating tests
- `chore:` - Maintenance tasks

## 🎯 Priority Areas

We're especially looking for contributions in these areas:

### Framework Support
- **Nuxt.js** - Vue-based framework support
- **Gatsby** - Static site generator
- **Svelte/SvelteKit** - Svelte framework support
- **Astro** - Modern static site generator

### AI Crawler Support
- **New AI bots** - Support for emerging AI crawlers
- **Bot-specific optimizations** - Custom rules per bot
- **AI-friendly features** - Better content discovery

### Advanced Features
- **Image optimization** - Automatic image sitemap generation
- **Multilingual support** - International SEO features
- **Performance optimization** - Faster page scanning
- **Custom templates** - User-defined template system

### Developer Experience
- **Better error messages** - More helpful debugging
- **Configuration validation** - Better config file validation
- **IDE support** - Schema definitions for YAML config
- **Debugging tools** - Better CLI debugging options

## 🤝 Community

- Join discussions in GitHub Issues
- Ask questions in GitHub Discussions
- Share your use cases and feedback
- Help others in the community

## 📋 Release Process

Releases are handled by maintainers:

1. Version bumping follows [SemVer](https://semver.org/)
2. Changelog is automatically generated
3. npm packages are published automatically
4. GitHub releases include detailed notes

## ❓ Questions?

If you have questions about contributing:

- Open a GitHub Discussion
- Create an issue with the `question` label
- Check existing documentation and issues

Thank you for contributing to vibe-seo! 🎉