339 lines
6.5 KiB
Markdown
339 lines
6.5 KiB
Markdown
# Contributing to HelmView
|
|
|
|
Thank you for your interest in contributing to HelmView! This document provides guidelines and instructions for contributing.
|
|
|
|
## 🎯 Ways to Contribute
|
|
|
|
- 🐛 Report bugs
|
|
- 💡 Suggest new features
|
|
- 📝 Improve documentation
|
|
- 🔧 Submit bug fixes
|
|
- ✨ Add new features
|
|
- 🎨 Improve UI/UX
|
|
- 🧪 Write tests
|
|
- 🌍 Translate (future)
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### Prerequisites
|
|
- Git
|
|
- Docker & Docker Compose
|
|
- Node.js 18+ (for local development)
|
|
- Python 3.11+ (for local development)
|
|
|
|
### Fork and Clone
|
|
```bash
|
|
# Fork the repository on GitHub
|
|
# Then clone your fork
|
|
git clone https://github.com/YOUR_USERNAME/helmview.git
|
|
cd helmview
|
|
```
|
|
|
|
### Development Setup
|
|
```bash
|
|
# Start the application
|
|
docker-compose up --build
|
|
|
|
# Or run locally
|
|
# Backend
|
|
cd backend
|
|
python -m venv venv
|
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
|
pip install -r requirements.txt
|
|
uvicorn main:app --reload
|
|
|
|
# Frontend (separate terminal)
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
## 📋 Development Workflow
|
|
|
|
### 1. Create a Branch
|
|
```bash
|
|
git checkout -b feature/my-new-feature
|
|
# or
|
|
git checkout -b fix/bug-description
|
|
```
|
|
|
|
### Branch Naming
|
|
- `feature/` - New features
|
|
- `fix/` - Bug fixes
|
|
- `docs/` - Documentation changes
|
|
- `refactor/` - Code refactoring
|
|
- `test/` - Test additions
|
|
- `chore/` - Maintenance tasks
|
|
|
|
### 2. Make Changes
|
|
|
|
#### Code Style
|
|
**Backend (Python)**
|
|
- Follow PEP 8
|
|
- Use type hints
|
|
- Add docstrings for functions
|
|
- Keep functions focused and small
|
|
|
|
**Frontend (JavaScript)**
|
|
- Use modern ES6+ syntax
|
|
- Follow React best practices
|
|
- Use functional components with hooks
|
|
- Keep components focused and reusable
|
|
|
|
#### Commit Messages
|
|
Follow the conventional commits format:
|
|
```
|
|
<type>(<scope>): <subject>
|
|
|
|
<body>
|
|
|
|
<footer>
|
|
```
|
|
|
|
Types:
|
|
- `feat`: New feature
|
|
- `fix`: Bug fix
|
|
- `docs`: Documentation
|
|
- `style`: Formatting
|
|
- `refactor`: Code restructuring
|
|
- `test`: Tests
|
|
- `chore`: Maintenance
|
|
|
|
Examples:
|
|
```bash
|
|
git commit -m "feat(editor): add YAML formatting button"
|
|
git commit -m "fix(upload): handle large file validation"
|
|
git commit -m "docs(readme): update installation steps"
|
|
```
|
|
|
|
### 3. Test Your Changes
|
|
|
|
#### Backend Tests
|
|
```bash
|
|
cd backend
|
|
pytest
|
|
# or with coverage
|
|
pytest --cov=. --cov-report=html
|
|
```
|
|
|
|
#### Frontend Tests
|
|
```bash
|
|
cd frontend
|
|
npm run test
|
|
# or with coverage
|
|
npm run test:coverage
|
|
```
|
|
|
|
#### Manual Testing
|
|
- Test all affected features
|
|
- Test error cases
|
|
- Test on different browsers (frontend)
|
|
- Verify Docker build works
|
|
|
|
### 4. Submit Pull Request
|
|
|
|
#### Before Submitting
|
|
- [ ] Code follows style guidelines
|
|
- [ ] Tests pass
|
|
- [ ] Documentation updated
|
|
- [ ] Commit messages are clear
|
|
- [ ] No merge conflicts
|
|
- [ ] Docker build succeeds
|
|
|
|
#### PR Description Template
|
|
```markdown
|
|
## Description
|
|
Brief description of changes
|
|
|
|
## Type of Change
|
|
- [ ] Bug fix
|
|
- [ ] New feature
|
|
- [ ] Breaking change
|
|
- [ ] Documentation update
|
|
|
|
## Testing
|
|
How to test these changes
|
|
|
|
## Screenshots (if applicable)
|
|
Add screenshots for UI changes
|
|
|
|
## Checklist
|
|
- [ ] Tests pass
|
|
- [ ] Documentation updated
|
|
- [ ] No breaking changes (or documented)
|
|
```
|
|
|
|
## 🐛 Reporting Bugs
|
|
|
|
### Before Reporting
|
|
1. Check existing issues
|
|
2. Verify it's reproducible
|
|
3. Test on latest version
|
|
|
|
### Bug Report Template
|
|
```markdown
|
|
**Describe the bug**
|
|
Clear description of the bug
|
|
|
|
**To Reproduce**
|
|
Steps to reproduce:
|
|
1. Go to '...'
|
|
2. Click on '...'
|
|
3. See error
|
|
|
|
**Expected behavior**
|
|
What should happen
|
|
|
|
**Actual behavior**
|
|
What actually happens
|
|
|
|
**Screenshots**
|
|
If applicable
|
|
|
|
**Environment**
|
|
- OS: [e.g., Windows 10]
|
|
- Browser: [e.g., Chrome 120]
|
|
- Version: [e.g., 1.0.0]
|
|
|
|
**Additional context**
|
|
Any other relevant information
|
|
```
|
|
|
|
## 💡 Feature Requests
|
|
|
|
### Feature Request Template
|
|
```markdown
|
|
**Is your feature request related to a problem?**
|
|
Description of the problem
|
|
|
|
**Describe the solution you'd like**
|
|
Clear description of desired feature
|
|
|
|
**Describe alternatives you've considered**
|
|
Alternative solutions or features
|
|
|
|
**Additional context**
|
|
Mockups, examples, etc.
|
|
```
|
|
|
|
## 📝 Documentation
|
|
|
|
### Documentation Guidelines
|
|
- Use clear, concise language
|
|
- Include code examples
|
|
- Add screenshots for UI features
|
|
- Keep README.md up to date
|
|
- Update API documentation
|
|
- Add inline code comments
|
|
|
|
### Documentation Locations
|
|
- `README.md` - Main documentation
|
|
- `QUICKSTART.md` - Quick start guide
|
|
- `SECURITY.md` - Security policy
|
|
- `docs/` - Detailed documentation (future)
|
|
- Code comments - Inline documentation
|
|
|
|
## 🎨 UI/UX Guidelines
|
|
|
|
### Design Principles
|
|
- **Simplicity**: Keep interfaces clean
|
|
- **Consistency**: Follow existing patterns
|
|
- **Accessibility**: WCAG 2.1 AA compliance
|
|
- **Responsiveness**: Mobile-friendly
|
|
- **Performance**: Fast loading times
|
|
|
|
### Color Palette
|
|
- Primary: `#667eea` (purple)
|
|
- Success: `#48bb78` (green)
|
|
- Warning: `#ed8936` (orange)
|
|
- Error: `#f56565` (red)
|
|
- Neutral: Shades of gray
|
|
|
|
## 🧪 Testing Guidelines
|
|
|
|
### Test Coverage Goals
|
|
- Backend: >80%
|
|
- Frontend: >70%
|
|
- Critical paths: 100%
|
|
|
|
### Test Types
|
|
1. **Unit Tests**: Individual functions
|
|
2. **Integration Tests**: API endpoints
|
|
3. **E2E Tests**: Full workflows (future)
|
|
4. **Security Tests**: Vulnerability scanning
|
|
|
|
## 🔒 Security
|
|
|
|
- Report security issues privately
|
|
- See [SECURITY.md](SECURITY.md) for details
|
|
- Never commit secrets or credentials
|
|
- Use environment variables
|
|
|
|
## 📦 Release Process
|
|
|
|
### Versioning
|
|
We follow [Semantic Versioning](https://semver.org/):
|
|
- MAJOR: Breaking changes
|
|
- MINOR: New features
|
|
- PATCH: Bug fixes
|
|
|
|
### Release Checklist
|
|
1. Update version numbers
|
|
2. Update CHANGELOG.md
|
|
3. Run full test suite
|
|
4. Update documentation
|
|
5. Create release tag
|
|
6. Build and test Docker images
|
|
7. Publish release notes
|
|
|
|
## 🤝 Code Review
|
|
|
|
### Review Process
|
|
1. Submit PR
|
|
2. Automated checks run
|
|
3. Maintainer reviews code
|
|
4. Address feedback
|
|
5. Approval and merge
|
|
|
|
### Review Criteria
|
|
- Code quality
|
|
- Test coverage
|
|
- Documentation
|
|
- Security considerations
|
|
- Performance impact
|
|
|
|
## 💬 Communication
|
|
|
|
### Channels
|
|
- **GitHub Issues**: Bug reports, features
|
|
- **GitHub Discussions**: Questions, ideas
|
|
- **Pull Requests**: Code review
|
|
- **Email**: Security issues only
|
|
|
|
### Response Times
|
|
- Critical bugs: 24-48 hours
|
|
- Other issues: 3-7 days
|
|
- Pull requests: 7-14 days
|
|
|
|
## 📜 License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the MIT License.
|
|
|
|
## 🙏 Recognition
|
|
|
|
Contributors will be:
|
|
- Listed in CONTRIBUTORS.md
|
|
- Mentioned in release notes
|
|
- Credited in documentation
|
|
|
|
## ❓ Questions?
|
|
|
|
- Check existing documentation
|
|
- Search closed issues
|
|
- Open a GitHub Discussion
|
|
- Contact maintainers
|
|
|
|
---
|
|
|
|
**Thank you for contributing to HelmView! 🎉**
|