mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-03 02:13:15 -04:00
Initial commit: ClaudeForge v1.0.0
This commit is contained in:
Reza Rezvani
@@ -0,0 +1,490 @@
|
||||
# Contributing to ClaudeForge
|
||||
|
||||
Thank you for your interest in contributing to ClaudeForge! This guide will help you get started.
|
||||
|
||||
---
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
By participating in this project, you agree to abide by our [Code of Conduct](../.github/CODE_OF_CONDUCT.md).
|
||||
|
||||
---
|
||||
|
||||
## How Can I Contribute?
|
||||
|
||||
### 1. Reporting Bugs
|
||||
|
||||
**Before submitting a bug report:**
|
||||
- Check existing issues to avoid duplicates
|
||||
- Collect information about the bug
|
||||
- Test with the latest version
|
||||
|
||||
**Submit a bug report:**
|
||||
- Use the bug report template
|
||||
- Provide clear title and description
|
||||
- Include steps to reproduce
|
||||
- Add relevant logs or screenshots
|
||||
- Mention your environment (OS, Claude Code version)
|
||||
|
||||
**Template:** https://github.com/alirezarezvani/ClaudeForge/issues/new?template=bug_report.md
|
||||
|
||||
---
|
||||
|
||||
### 2. Suggesting Enhancements
|
||||
|
||||
**Before submitting:**
|
||||
- Check if the feature already exists
|
||||
- Review planned features in CHANGELOG.md
|
||||
- Consider if it fits project scope
|
||||
|
||||
**Submit an enhancement:**
|
||||
- Use the feature request template
|
||||
- Explain the use case
|
||||
- Describe proposed solution
|
||||
- Consider alternatives
|
||||
|
||||
**Template:** https://github.com/alirezarezvani/ClaudeForge/issues/new?template=feature_request.md
|
||||
|
||||
---
|
||||
|
||||
### 3. Contributing Code
|
||||
|
||||
#### Quick Start
|
||||
|
||||
```bash
|
||||
# Fork the repository
|
||||
# Clone your fork
|
||||
git clone https://github.com/YOUR-USERNAME/ClaudeForge.git
|
||||
cd ClaudeForge
|
||||
|
||||
# Create a branch
|
||||
git checkout -b feature/amazing-feature
|
||||
|
||||
# Make your changes
|
||||
# Test your changes
|
||||
./install.sh # Test installation
|
||||
/enhance-claude-md # Test in Claude Code
|
||||
|
||||
# Commit your changes
|
||||
git commit -m "Add amazing feature"
|
||||
|
||||
# Push to your fork
|
||||
git push origin feature/amazing-feature
|
||||
|
||||
# Open a Pull Request
|
||||
```
|
||||
|
||||
#### Development Setup
|
||||
|
||||
```bash
|
||||
# Install development dependencies
|
||||
# (None required - Python standard library only)
|
||||
|
||||
# Test Python modules
|
||||
python3 -c "from skill.analyzer import CLAUDEMDAnalyzer; print('OK')"
|
||||
|
||||
# Test installation scripts
|
||||
./install.sh
|
||||
# Choose option 2 (project-level) for testing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Python Code Style
|
||||
|
||||
**Follow PEP 8:**
|
||||
```python
|
||||
# Good
|
||||
def analyze_file(self, content: str) -> Dict[str, Any]:
|
||||
"""Analyze CLAUDE.md file content."""
|
||||
pass
|
||||
|
||||
# Bad
|
||||
def analyzeFile(self,content):
|
||||
pass
|
||||
```
|
||||
|
||||
**Type Hints:**
|
||||
```python
|
||||
# Always use type hints
|
||||
def calculate_score(sections: List[str]) → int:
|
||||
return len(sections) * 10
|
||||
```
|
||||
|
||||
**Docstrings:**
|
||||
```python
|
||||
def validate_length(self, content: str) -> bool:
|
||||
"""
|
||||
Validate CLAUDE.md file length.
|
||||
|
||||
Args:
|
||||
content: File content as string
|
||||
|
||||
Returns:
|
||||
True if length is valid, False otherwise
|
||||
"""
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Markdown Style
|
||||
|
||||
**Headings:**
|
||||
```markdown
|
||||
# H1 - Document title
|
||||
## H2 - Main sections
|
||||
### H3 - Subsections
|
||||
```
|
||||
|
||||
**Code Blocks:**
|
||||
```markdown
|
||||
```bash
|
||||
# Use language-specific syntax highlighting
|
||||
command here
|
||||
```
|
||||
```
|
||||
|
||||
**Links:**
|
||||
```markdown
|
||||
# Prefer relative links for internal docs
|
||||
[Architecture](ARCHITECTURE.md)
|
||||
|
||||
# Use absolute URLs for external
|
||||
[GitHub](https://github.com/alirezarezvani/ClaudeForge)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Testing Your Changes
|
||||
|
||||
#### Test Python Modules
|
||||
|
||||
```bash
|
||||
# Test analyzer
|
||||
python3 << EOF
|
||||
from skill.analyzer import CLAUDEMDAnalyzer
|
||||
content = open('test-CLAUDE.md').read()
|
||||
analyzer = CLAUDEMDAnalyzer(content)
|
||||
report = analyzer.analyze_file()
|
||||
print(f"Quality Score: {report['quality_score']}")
|
||||
EOF
|
||||
```
|
||||
|
||||
#### Test Installation
|
||||
|
||||
```bash
|
||||
# Test install.sh
|
||||
./install.sh
|
||||
# Choose option 2 (project-level)
|
||||
# Verify all components copied correctly
|
||||
|
||||
# Test uninstall
|
||||
rm -rf ./.claude
|
||||
```
|
||||
|
||||
#### Test in Claude Code
|
||||
|
||||
```bash
|
||||
# Install your changes
|
||||
./install.sh
|
||||
|
||||
# Restart Claude Code
|
||||
|
||||
# Test slash command
|
||||
/enhance-claude-md
|
||||
|
||||
# Verify output matches expected behavior
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Contribution Areas
|
||||
|
||||
### 1. Adding New Templates
|
||||
|
||||
**Location:** `skill/examples/`
|
||||
|
||||
**Steps:**
|
||||
1. Create new template file (e.g., `rust-cli-CLAUDE.md`)
|
||||
2. Follow native format structure
|
||||
3. Update `skill/examples/README.md`
|
||||
4. Update `template_selector.py` detection logic
|
||||
5. Add test case to `sample_input.json`
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Create Rust template
|
||||
vim skill/examples/rust-cli-CLAUDE.md
|
||||
|
||||
# Update selector
|
||||
vim skill/template_selector.py
|
||||
# Add: if 'Cargo.toml' in files: return 'rust-cli'
|
||||
|
||||
# Test
|
||||
# Create test Rust project, run /enhance-claude-md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Improving Detection Logic
|
||||
|
||||
**Location:** `skill/workflow.py`
|
||||
|
||||
**Methods to enhance:**
|
||||
- `_detect_project_type()`
|
||||
- `_detect_tech_stack()`
|
||||
- `_estimate_team_size()`
|
||||
- `_detect_development_phase()`
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Add Flutter detection
|
||||
def _detect_project_type(self, results):
|
||||
files = results.get('files', [])
|
||||
|
||||
# Add Flutter check
|
||||
if 'pubspec.yaml' in files:
|
||||
return 'mobile'
|
||||
|
||||
# ... existing logic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Enhancing Quality Scoring
|
||||
|
||||
**Location:** `skill/analyzer.py`
|
||||
|
||||
**Method:** `calculate_quality_score()`
|
||||
|
||||
**Ideas:**
|
||||
- Add more granular checks
|
||||
- Weight sections by importance
|
||||
- Detect project-specific customization
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
def calculate_quality_score(self) -> int:
|
||||
score = 0
|
||||
|
||||
# Add new check: Has examples
|
||||
if self._has_code_examples():
|
||||
score += 5 # Bonus points
|
||||
|
||||
# ... existing logic
|
||||
return min(score, 100)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Adding New Validation Rules
|
||||
|
||||
**Location:** `skill/validator.py`
|
||||
|
||||
**Steps:**
|
||||
1. Add new validation method
|
||||
2. Call from `validate_all()`
|
||||
3. Return standard validation result
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
def validate_examples(self) -> Dict[str, Any]:
|
||||
"""Validate code examples are present."""
|
||||
code_blocks = re.findall(r'```.*?```', self.content, re.DOTALL)
|
||||
|
||||
return {
|
||||
'passed': len(code_blocks) >= 3,
|
||||
'message': 'At least 3 code examples required',
|
||||
'severity': 'low'
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Documentation Improvements
|
||||
|
||||
**Areas:**
|
||||
- Fix typos or unclear explanations
|
||||
- Add missing examples
|
||||
- Improve installation instructions
|
||||
- Translate to other languages (future)
|
||||
|
||||
**Process:**
|
||||
1. Edit markdown files in `docs/`
|
||||
2. Test markdown rendering locally
|
||||
3. Submit pull request
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
### 1. Before Submitting
|
||||
|
||||
- [ ] Code follows project style guidelines
|
||||
- [ ] All tests pass (manual testing required)
|
||||
- [ ] Documentation updated if needed
|
||||
- [ ] CHANGELOG.md updated with your changes
|
||||
- [ ] Commit messages are clear and descriptive
|
||||
|
||||
### 2. Submitting
|
||||
|
||||
1. **Create Pull Request** from your fork
|
||||
2. **Fill out PR template** completely
|
||||
3. **Link related issues** (if any)
|
||||
4. **Request review** from maintainers
|
||||
5. **Respond to feedback** promptly
|
||||
|
||||
### 3. After Submission
|
||||
|
||||
- **CI checks** will run automatically
|
||||
- **Maintainers** will review your code
|
||||
- **Address feedback** by pushing new commits
|
||||
- **Don't force-push** after review started
|
||||
- **Be patient** - reviews may take a few days
|
||||
|
||||
### 4. Merging
|
||||
|
||||
Once approved:
|
||||
- Maintainer will merge your PR
|
||||
- Your contribution will be in the next release
|
||||
- You'll be added to contributors list
|
||||
|
||||
---
|
||||
|
||||
## Commit Message Guidelines
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
type(scope): Short description
|
||||
|
||||
Longer description if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Code style changes (no logic change)
|
||||
- `refactor`: Code refactoring
|
||||
- `test`: Adding tests
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
feat(analyzer): Add code example detection
|
||||
|
||||
Adds check for code examples in CLAUDE.md files.
|
||||
Contributes to quality score calculation.
|
||||
|
||||
Fixes #45
|
||||
```
|
||||
|
||||
```
|
||||
fix(installer): Resolve Windows path issues
|
||||
|
||||
Fixes path separator issues on Windows platforms.
|
||||
Updates install.ps1 to use platform-specific paths.
|
||||
|
||||
Fixes #67
|
||||
```
|
||||
|
||||
```
|
||||
docs(quick-start): Clarify installation steps
|
||||
|
||||
Adds more detailed explanations for each step.
|
||||
Includes troubleshooting for common issues.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Release Process
|
||||
|
||||
(For maintainers)
|
||||
|
||||
### Version Numbering
|
||||
|
||||
Follow Semantic Versioning (MAJOR.MINOR.PATCH):
|
||||
- MAJOR: Breaking changes
|
||||
- MINOR: New features (backward compatible)
|
||||
- PATCH: Bug fixes (backward compatible)
|
||||
|
||||
### Release Checklist
|
||||
|
||||
1. **Update version:**
|
||||
- `CHANGELOG.md` - Add new version section
|
||||
- `README.md` - Update version badge
|
||||
- `skill/SKILL.md` - Update version footer
|
||||
|
||||
2. **Create release:**
|
||||
```bash
|
||||
git tag -a v1.1.0 -m "Release v1.1.0"
|
||||
git push origin v1.1.0
|
||||
```
|
||||
|
||||
3. **GitHub Release:**
|
||||
- Create release from tag
|
||||
- Copy CHANGELOG excerpt to description
|
||||
- Attach any binaries if needed
|
||||
|
||||
4. **Announce:**
|
||||
- GitHub Discussions
|
||||
- Social media (if applicable)
|
||||
- Update documentation site
|
||||
|
||||
---
|
||||
|
||||
## Community
|
||||
|
||||
### Getting Help
|
||||
|
||||
- **GitHub Discussions:** Ask questions, share ideas
|
||||
- **GitHub Issues:** Report bugs, request features
|
||||
- **Documentation:** Comprehensive guides in `docs/`
|
||||
|
||||
### Staying Updated
|
||||
|
||||
- **Watch Repository:** Get notifications for releases
|
||||
- **Star Repository:** Show support, stay informed
|
||||
- **Follow Updates:** Check CHANGELOG.md for changes
|
||||
|
||||
---
|
||||
|
||||
## Recognition
|
||||
|
||||
Contributors are recognized in:
|
||||
- **README.md** - Contributors section
|
||||
- **CHANGELOG.md** - Version-specific contributors
|
||||
- **GitHub** - Automatic contributors graph
|
||||
|
||||
Every contribution matters, from code to documentation to bug reports!
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
- **General Questions:** GitHub Discussions
|
||||
- **Bug Reports:** GitHub Issues
|
||||
- **Security Issues:** Email maintainers directly (see SECURITY.md if created)
|
||||
- **Feature Requests:** GitHub Issues with feature template
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the MIT License.
|
||||
|
||||
See [LICENSE](../LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
**Thank you for contributing to ClaudeForge!** 🎉
|
||||
|
||||
Your contributions help make CLAUDE.md management better for everyone in the Claude Code community.
|
||||
Reference in New Issue
Block a user