🐬 Dolphain

Fork & Clone

Create your own copy of the repository. You'll work here safely without affecting the main project.

git clone https://github.com/YOUR-USERNAME/dolphain.git
cd dolphain
git remote add upstream https://github.com/micha2718l/dolphain.git

⚠️ Important: You cannot push directly to main. This is intentional! It keeps the project safe and encourages good collaboration practices.

Create a Branch

Always work on a feature branch. Name it something descriptive.

git checkout -b feature/whistle-detection
# or
git checkout -b docs/improve-readme
# or
git checkout -b fix/batch-processing-bug

💡 Tip: Use prefixes like feature/, docs/, fix/, experiment/ to keep things organized.

Set Up Your Environment

Get Python and dependencies installed. Use the AI to help you!

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e .

# Install dev dependencies if you're adding tests
pip install pytest matplotlib numpy scipy

🤖 Pro Tip: Ask your AI assistant: "Help me set up the Dolphain development environment"

Read the Context

Before diving in, understand where we are. These docs are your map!

• CONTINUATION_GUIDE.md - Comprehensive overview & next steps
• PROJECT_STATUS.md - Current state of the project
• README.md - Installation & basic usage
• SESSION_STATE.md - Latest session notes

📖 Why? These docs minimize lost time when context windows clear or collaborators switch.

Pick Your Adventure

What sounds fun to you? Choose based on your interests!

Vibe Code with Your AI

Here's where the magic happens! Partner with an LLM to build.

🌟 Remember: You're the creative director. The AI is your implementation partner.

Commit Often, Document Always

Make small, frequent commits with clear messages.

git add dolphain/signal.py
git commit -m "Add whistle detection using spectrogram peaks

- Implement peak finding with scipy
- Add frequency range filtering (2-20 kHz)
- Include docstrings and type hints
- Add basic unit tests"

git push origin feature/whistle-detection

💎 Good commits: Explain WHAT and WHY, not just WHAT. Future readers will love you!

Update the Docs

Before you finish, update relevant documentation.

• Add your feature to README.md
• Update PROJECT_STATUS.md with what's complete
• Create or update SESSION_STATE.md with your progress
• If you finished a big feature, add a new doc file (like WHISTLE_DETECTION.md)

📚 Why? Documentation is a gift to the next contributor (who might be you in 3 months!).

Create a Pull Request

Share your work! Go to GitHub and open a PR.

## What This PR Does
Brief description of the feature/fix

## Changes Made
- List of specific changes
- Be clear and concise

## Testing
How you tested this (manual tests, unit tests, etc.)

## Documentation Updated
- [ ] README.md
- [ ] PROJECT_STATUS.md  
- [ ] Relevant guide docs
- [ ] Inline code comments

## Notes for Reviewer
Anything special to know? Any decisions you made?

## AI Collaboration Notes
Which AI you used, what worked well, any challenges?

🎉 Celebrate: You just contributed to dolphin communication research!