Skip to content

docs: add comprehensive contributing guide #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paralleliq merged 1 commit into from
Jan 15, 2026
Merged

docs: add comprehensive contributing guide #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 212 additions & 20 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,232 @@
# Contributing to ModelSpec

Thank you for your interest in contributing!
Thank you for your interest in contributing to ModelSpec - a declarative specification for AI model deployment.

ModelSpec is an open specification, and we welcome thoughtful contributions that improve clarity, usability, and real-world applicability.
---

## Repository Structure

ModelSpec is part of the ParallelIQ ecosystem:
- **modelspec**: Core specification and schema for AI model deployment
- **piqc-knowledge-base**: Documentation, examples, and knowledge resources that provide context for ModelSpec

---

## Ways to Contribute
## How to Contribute

### 1. Fork and Clone

```bash
# Fork the repo on GitHub, then clone YOUR fork:
git clone https://github.com/YourUsername/modelspec.git
cd modelspec

# Add upstream remote
git remote add upstream https://github.com/paralleliq/modelspec.git

# Verify remotes
git remote -v
```

### 2. Sync and Create Branch

```bash
# Sync with latest changes
git checkout main
git pull upstream main
git push origin main

# Create feature branch from main
git checkout -b feature/your-feature-name
```

**Branch Naming:**
- `feature/` - New features or schema additions
- `fix/` - Bug fixes or spec corrections
- `docs/` - Documentation improvements

### 3. Make Your Changes

**Guidelines:**
- Keep ModelSpec **declarative** - avoid deployment logic
- Remain **platform-agnostic** - no vendor lock-in
- Update examples in piqc-knowledge-base if relevant
- Follow existing schema patterns

### 4. Commit and Push

```bash
# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add GPU resource specification schema"

# Push to YOUR fork
git push origin feature/your-feature-name
```

**Commit Format:** `type: description`
- `feat:` - New feature or schema addition
- `fix:` - Bug fix or correction
- `docs:` - Documentation update
- `chore:` - Maintenance tasks

### 5. Create Pull Request

1. Go to your fork on GitHub: `https://github.com/YourUsername/modelspec`
2. Click **"Compare & pull request"**
3. Ensure:
- Base: `paralleliq/modelspec` `main`
- Head: `YourUsername/modelspec` `feature/your-feature-name`
4. Fill in PR description:

```markdown
## Description
Brief summary of what this PR does

## Changes Made
- Added X schema field
- Updated Y documentation
- Fixed Z validation issue

## Related Issues
Closes #123

## Testing
How you verified these changes work

## Checklist
- [ ] Schema changes are backward compatible
- [ ] Documentation updated
- [ ] Examples added/updated in piqc-knowledge-base (if applicable)
- [ ] Follows declarative principles
```

5. Submit PR

### 6. Address Review Feedback

```bash
# Make requested changes
# Edit files...

You can help by:
- Reporting issues or ambiguities in the spec or examples
- Suggesting improvements to the schema or documentation
- Adding or refining example ModelSpec files
- Improving explanations or tutorials
# Commit and push updates
git add .
git commit -m "fix: address review feedback on schema validation"
git push origin feature/your-feature-name
```

The PR automatically updates with new commits.

### 7. After PR Merges

```bash
# Update your main branch
git checkout main
git pull upstream main
git push origin main

# Delete feature branch
git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name
```

---

## Contribution Types

### Schema Improvements
- Add new model configuration fields
- Enhance validation rules
- Improve schema documentation

### Documentation
- Clarify existing specifications
- Add usage examples
- Improve README and guides

### Examples
- Provide real-world ModelSpec files
- Add deployment scenario examples
- Contribute to piqc-knowledge-base

### Bug Reports
- Report ambiguities or issues
- Suggest corrections
- Identify edge cases

---

## Contribution Guidelines
## What to Contribute

Please ensure that contributions:
- **Keep ModelSpec declarative** – avoid adding deployment, orchestration, or enforcement logic
- **Remain platform-agnostic** – do not tie the spec to any specific runtime or vendor
- **Are documented** – explain the rationale for changes or additions
### ✅ Welcome
- Schema enhancements for model deployment
- Platform-agnostic configuration options
- Clear documentation and examples
- Validation improvements
- Real-world use cases

When in doubt, open an issue for discussion before submitting a PR.
### ❌ Avoid
- Deployment orchestration logic
- Vendor-specific implementations
- Runtime enforcement mechanisms
- Breaking changes without discussion

---

## Pull Requests
## Design Principles

- Keep pull requests focused and well-scoped
- Update documentation or examples alongside schema changes
- Include comments or a clear description explaining *why* the change is needed
1. **Declarative** - Describe "what", not "how"
2. **Platform-agnostic** - Works across any infrastructure
3. **Composable** - Modules can be combined
4. **Versioned** - Schema changes are tracked
5. **Documented** - Every field has clear purpose

---

## Community Standards
## Getting Help

- **Questions**: Open a GitHub Discussion
- **Bugs**: Create an Issue with details
- **Ideas**: Open an Issue for discussion first
- **Docs**: Check piqc-knowledge-base repo

---

## Quick Command Reference

```bash
# Setup (once)
git clone https://github.com/YourUsername/modelspec.git
cd modelspec
git remote add upstream https://github.com/paralleliq/modelspec.git

# Start work
git checkout main && git pull upstream main && git push origin main
git checkout -b feature/name

# During work
git add .
git commit -m "type: description"
git push origin feature/name

# After merge
git checkout main && git pull upstream main && git push origin main
git branch -d feature/name
git push origin --delete feature/name
```

---

## License

By contributing, you agree that your contributions will be licensed under the same Business Source License 1.1 that covers this project. See [LICENSE](LICENSE) for details.

---

## Community

All contributors must follow our [Code of Conduct](CODE_OF_CONDUCT.md). Be respectful, constructive, and collaborative.

All contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
Thank you for helping make ModelSpec better! 🚀