Contributing to OpenPets 🐾

Welcome to the OpenPets pet shelter! We're thrilled you want to help us breed new pets and improve our ecosystem. This guide will help you get started contributing to our friendly community.

Our Pet-Themed Philosophy

At OpenPets, we believe in making developer tools feel like companions rather than infrastructure. Our terminology reflects this:

• Plugins → Pets (they're our friends!)
• Installing → Adopting (give a pet a home)
• Creating → Breeding (bring new pets to life)
• Registry → Pet Shelter (where pets find families)
• Configuring → Training (teach your pet new tricks)
• Errors → Pet needs attention (gentle reminders)

Ways to Contribute 🏆

🐕 Breed New Pets

Create integrations for services you love! Check out the _TEMPLATE_ folder to get started.

# Start with our template
cd pets/
cp -r _TEMPLATE_ my-awesome-pet
cd my-awesome-pet

# Follow the setup guide in AGENTS.md

🐾 Improve Existing Pets

Help train our current pets to be better companions:

• Fix bugs and improve reliability
• Add new features and capabilities
• Update documentation and examples

🏠 Improve the Pet Shelter

Enhance the core OpenPets experience:

• CLI improvements and new commands
• Desktop app features
• Documentation and guides
• Testing and validation tools

🎨 Design & Branding

Help us make OpenPets more delightful:

• Visual design and mascots
• Website improvements
• Community features like "Pet of the Month"

Getting Started 🚀

1. Set Up Your Environment

# Clone the repository
git clone https://github.com/your-org/openpets.git
cd openpets

# Install dependencies
bun install

# Install the CLI globally for development
npm link

2. Explore the Codebase

• pets/ - Individual pet implementations
• src/core/ - Core OpenPets framework
• src/core/cli.ts - Primary CLI entrypoint
• apps/desktop/ - Tauri desktop application
• AGENTS.md - Detailed development guide

3. Run Tests

# Validate all pets
pets validate

# Test a specific pet
cd pets/my-pet
pets run my-pet

# Run scenarios
bun run test:scenarios my-pet

Maintenance and Recovery

Use the safe maintenance scripts first:

# Remove build artifacts only (safe default)
bun run clean

# Clean artifacts and re-sync dependencies
bun run reset

If you need a full dependency wipe (for lockfile corruption or deep workspace issues), use the explicit hard variants:

# Destructive cleanup (deletes all node_modules + lockfile)
bun run clean:hard

# Destructive cleanup plus reinstall
bun run reset:hard

Tips:

• Use bun scripts/maintenance.ts <mode> --dry-run to preview affected paths.
• Prefer reset before reset:hard; hard mode is intended for recovery only.
• If a hard reset fails mid-install, run bun install again from repo root.

Breeding New Pets 🐱

Pet Requirements

Every good pet needs:

1. Health Check - {pet-name}-test-connection tool
2. Graceful Degradation - Work when not fully configured
3. Proper Training - Clear error messages and logging
4. Good Documentation - README, queries, and scenarios

Pet Anatomy

pets/my-pet/
├── index.ts          # Main pet implementation
├── package.json      # Pet metadata and configuration
├── README.md         # Pet care guide
└── src/              # Additional pet logic

Naming Conventions

• Use kebab-case for pet names: my-awesome-pet
• Tool names: {pet-name}-{action} (e.g., jira-list-issues)
• Environment variables: {PET_NAME}_API_KEY

Submitting Changes 📝

Commit Message Format

We use Conventional Commits enforced by commitlint:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types:

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting, missing semicolons, etc.
refactor	Code change that neither fixes nor adds
perf	Performance improvement
test	Adding or correcting tests
chore	Maintenance tasks
ci	CI/CD changes
build	Build system changes
pet	Pet-specific changes
release	Release commits

Examples:

# New feature for a pet
feat(jira): add bulk issue creation tool

# Bug fix in core
fix(core): resolve type export conflicts

# Documentation update
docs: add commit message guidelines

# Pet-specific change
pet(stripe): add subscription management

# CI/CD update
ci: switch all workflows to bun

Scope (optional but encouraged):

• Pet name: jira, github, stripe
• Package: core, sdk, cli
• Infrastructure: ci, deps, scripts

Pull Request Process

1. Fork the repository
2. Create a descriptive branch: feat/add-github-pet
3. Make your changes following our patterns
4. Test thoroughly:

   pets validate
   bun run lint
   bun run typecheck

5. Commit with conventional commit messages (enforced by hooks)
6. Open a pull request with:
   • A conventional PR title such as feat(github): add issue search
   • A linked issue for non-docs work: Closes #123 or Relates to #123
   • Clear testing or verification steps

Issue First Policy

For most behavior changes, new features, and pet work, start with an issue first.

• Link the issue in your PR with Fixes #123, Closes #123, or Relates to #123
• Small docs-only changes can usually skip the issue
• If you are unsure whether something belongs in OpenPets, open an issue before building it

PR Titles

PR titles should follow conventional commit style so they are easy to triage and easy to scan in changelogs.

• feat: new functionality
• fix: bug fixes
• pet: pet-specific work
• docs: documentation only
• refactor: internal improvement without behavior change
• test: new or updated tests
• ci: workflow or automation changes
• perf: performance improvements

Scopes are optional but encouraged when they add clarity:

• feat(jira): add bulk issue lookup
• fix(core): handle missing env loading
• docs(contributing): simplify issue policy

Good PR Descriptions

Keep PR descriptions short, specific, and written in your own words.

• Explain the problem and the change
• Explain how you verified it
• Include screenshots for UI or docs visuals when helpful
• Avoid long AI-generated walls of text

PR Template

Use our PR template (.github/pull_request_template.md) to keep PRs reviewable and searchable. If you are adding a brand new pet scaffold, use .github/PULL_REQUEST_TEMPLATE/new-pet-scaffold.md instead.

Code Style 🐾

TypeScript Guidelines

• Use openpets-sdk imports, not direct dependencies
• Follow existing patterns in similar pets
• Include proper error handling and logging
• Return JSON strings from all tools

Schema Requirements

Only use these Zod types (runtime compatibility limit):

• ✅ z.string(), z.number(), z.boolean()
• ✅ z.array(z.string()), z.array(z.number())
• ✅ z.object({ field: z.string() })
• ✅ z.enum(["value1", "value2"])
• ❌ Nested objects in arrays
• ❌ Complex unions or records

For complex data, use JSON string serialization:

schema: z.object({
  dataJson: z.string().describe("JSON string of complex data")
}),
execute(args) {
  const data = JSON.parse(args.dataJson)
}

Community Guidelines 🤝

Be Friendly and Welcoming

• Use pet-themed language when appropriate
• Help newcomers feel at home in our shelter
• Assume good intent and be patient

Communication

• Use GitHub Discussions for questions and conversations
• Use GitHub Issues for bug reports and feature requests
• Share your pet creations and success stories!

Recognition

• Contributors get special recognition in our releases
• Outstanding pet creators may be featured as "Pet of the Month"
• Help build the most delightful developer ecosystem

Getting Help 🆘

• Documentation: Check AGENTS.md for detailed guides
• Examples: Browse existing pets in the pets/ directory
• Issues: Search existing issues before creating new ones
• Discussions: Use GitHub Discussions for questions

Release Process 📦

Pets are published by the scheduled/manual publish workflow after changes land on main:

1. Merge pet changes to main
2. Scheduled or manual publish workflow validation and testing
3. Publication to npm as @openpets/pet-name
4. npm visibility verification and registry update

Thank you for helping us make OpenPets the most delightful developer ecosystem! 🎉

---

Remember: In OpenPets, every contribution helps make our pet shelter a better home for developers and their digital companions.