CONTRIBUTING.md

# Contributing to TSU-WAVE

We welcome contributions from tsunami researchers, coastal engineers, hydrodynamic physicists, and software developers. This guide explains how to contribute to the project.

## Ways to Contribute

### 1. Report Issues or Suggest Improvements
- Open a new Issue on [GitLab](https://gitlab.com/gitdeeper4/tsu-wave/-/issues) or [GitHub](https://github.com/gitdeeper4/tsu-wave/issues)
- Describe the problem or suggestion in detail
- Include relevant data or references if applicable
- Add appropriate labels (bug, enhancement, question, physics)

### 2. Code Contributions
1. Fork the repository on your preferred platform
2. Create a new branch (`git checkout -b feature/your-feature`)
3. Implement your changes following our guidelines
4. Test your changes thoroughly
5. Submit a Pull Request/Merge Request

### 3. Documentation Contributions
- Improve README.md or documentation files
- Add examples and tutorials
- Translate documentation to other languages
- Write scientific explanations of parameters

### 4. Scientific Contributions
- Propose new physical parameters or indicators
- Review methodology and derivations
- Suggest improved measurement techniques
- Share validation data from tsunami events
- Contribute case studies of historical tsunamis

### 5. Data Contributions
- Share DART buoy records (with appropriate attribution)
- Contribute tide gauge data from tsunami events
- Provide bathymetric survey data
- Share run-up survey measurements

## Code Requirements
- **Python**: Follow PEP 8 standards
- **Fortran**: Follow consistent formatting for NSWE solver
- **Tests**: Write tests for new code (pytest)
- **Documentation**: Document functions and classes with docstrings
- **Type Hints**: Use type hints in Python code
- **Performance**: Optimize numerical computations

## Development Process
1. **Discuss**: Open an Issue to discuss major changes first
2. **Plan**: Define requirements and design
3. **Develop**: Write code with comprehensive tests
4. **Review**: Submit for review by maintainers
5. **Merge**: Approved changes merged into main branch

## Acceptance Criteria
- ✅ Code compiles/runs without errors
- ✅ All tests pass (run `pytest tests/ -v`)
- ✅ New code has test coverage ≥ 90%
- ✅ Documentation is updated
- ✅ No conflicts with main branch
- ✅ Follows project coding standards
- ✅ Physical derivations are mathematically sound

## Testing
```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Run all tests
pytest tests/ -v

# Run specific test module
pytest tests/test_wcc.py

# Run with coverage
pytest --cov=src/ tests/
```

Pull Request Process

1. Update the README.md or documentation with details of changes
2. Update CHANGELOG.md with your contribution
3. Ensure all tests pass in CI/CD pipeline
4. Request review from at least one maintainer
5. Address review comments
6. Squash commits if requested

Scientific Review Process

For contributions involving new physics or parameters:

1. Provide complete mathematical derivation
2. Include references to peer-reviewed literature
3. Validate against at least 3 tsunami events
4. Submit with validation data and results
5. Undergo review by scientific advisory board

Communication Channels

Platform Purpose Link
GitLab Issues Bug reports, feature requests gitlab.com/gitdeeper4/tsu-wave/-/issues
GitHub Issues Mirror github.com/gitdeeper4/tsu-wave/issues
Email Direct contact gitdeeper@gmail.com
ORCID Researcher ID 0009-0003-8903-0029

Code of Conduct

· Be respectful and inclusive
· Provide constructive feedback
· Focus on scientific accuracy and technical excellence
· Acknowledge contributions appropriately
· Follow open science principles

License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to TSU-WAVE! 🌊

Together, we can improve tsunami early warning and save lives.

Last Updated: February 17, 2026