> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/appertafoundation/openeyes/llms.txt
> Use this file to discover all available pages before exploring further.
# Contributing
> How to contribute to the OpenEyes project
We welcome contributions to OpenEyes! This guide covers the process for contributing code, reporting issues, and working with the development team.
## Before You Start
If you are thinking of making a contribution to OpenEyes, please contact the team at **[openeyes@apperta.org](mailto:openeyes@apperta.org)** before starting work.
This ensures:
* Your contribution aligns with project goals
* No duplicate effort with ongoing work
* You have the necessary guidance and support
## Getting Started
### Repository Access
The main OpenEyes repository is:
```
https://github.com/AppertaFoundation/openeyes
```
If you need to share repositories with the core development team, organizational members are listed at:
```
https://github.com/openeyes
```
### Fork and Clone
1. Fork the repository on GitHub
2. Clone your fork locally:
```bash theme={null}
git clone https://github.com/YOUR_USERNAME/openeyes.git
cd openeyes
```
3. Add the upstream remote:
```bash theme={null}
git remote add upstream https://github.com/AppertaFoundation/openeyes.git
```
## Git Workflow
OpenEyes follows the **gitflow** branching model.
### Branch Structure
* **master** - Stable release branch (production-ready code)
* **develop** - Bleeding edge development (integration branch)
* **feature/** - New features
* **hotfix/** - Critical fixes for production
* **release/** - Release preparation
For bleeding edge development, use the **develop** branch. For stable releases, use **master**.
### Creating a Feature Branch
```bash theme={null}
# Start from develop
git checkout develop
git pull upstream develop
# Create your feature branch
git checkout -b feature/your-feature-name
```
### Branch Naming
Use descriptive branch names:
```bash theme={null}
feature/patient-search-improvements
feature/examination-element-allergies
hotfix/critical-login-bug
```
## Coding Standards
OpenEyes follows **PSR-12** coding standards with some exceptions.
### PHP CodeSniffer
Check your code before committing:
```bash theme={null}
# Check code style
vendor/bin/phpcs --standard=phpcs.xml protected/modules/YourModule
# Auto-fix issues
vendor/bin/phpcbf --standard=phpcs.xml protected/modules/YourModule
```
### Code Style Rules
Key rules from `phpcs.xml`:
```xml phpcs.xml theme={null}
```
### PHPStan Static Analysis
Run static analysis:
```bash theme={null}
vendor/bin/phpstan analyse
```
Configuration (`phpstan.neon`):
```yaml theme={null}
parameters:
level: 0
phpVersion: 80000
scanDirectories:
- vendor/yiisoft/yii/framework
- protected/modules
```
### Best Practices
1. **Follow existing patterns** - Match the style of surrounding code
2. **Use meaningful names** - Variables, methods, and classes should be self-documenting
3. **Comment complex logic** - Explain why, not what
4. **Keep methods short** - Single responsibility principle
5. **Write tests** - All new code should have tests
6. **Use type hints** - Where possible in PHP 7.4+
7. **Handle errors** - Don't ignore exceptions
## Testing Requirements
All contributions must include appropriate tests.
### Required Tests
1. **Unit tests** for individual classes/methods
2. **Feature tests** for user-facing functionality
3. **Integration tests** for module interactions
### Running Tests
```bash theme={null}
# Run all tests
oe-unit-tests --group=sample-data
# Run your new tests
oe-unit-tests --filter=YourTestClass
# Run Cypress E2E tests
npx cypress run
```
### Test Requirements
* All tests must pass before submitting PR
* New features require new tests
* Bug fixes should include regression tests
* Tag tests with `@group sample-data`
See [Testing](/development/testing) for detailed testing guidelines.
## Making Changes
### Development Process
1. **Create feature branch** from develop
2. **Make your changes** following coding standards
3. **Write tests** for new functionality
4. **Run tests** to ensure nothing breaks
5. **Check code style** with phpcs
6. **Commit your changes** with clear messages
### Commit Messages
Write clear, descriptive commit messages:
```bash theme={null}
# Good commit messages
git commit -m "Add allergy checking to examination element"
git commit -m "Fix patient search pagination bug"
git commit -m "Update medication model validation rules"
# Bad commit messages
git commit -m "Fixed stuff"
git commit -m "WIP"
git commit -m "Changes"
```
### Commit Message Format
```
: