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 [e-mail] 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:

git clone https://github.com/YOUR_USERNAME/openeyes.git
cd openeyes

3. Add the upstream remote:

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

# 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:

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:

# 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:

phpcs.xml

<ruleset name="OpenEyes Coding Standards">
    <rule ref="PSR12">
        <!-- Class names don't need to be CamelCase (legacy) -->
        <exclude name="Squiz.Classes.ValidClassName.NotCamelCaps" />
    </rule>

    <rule ref="PSR1">
        <!-- Namespaces not required (legacy code) -->
        <exclude name="PSR1.Classes.ClassDeclaration.MissingNamespace" />
        <exclude name="PSR1.Methods.CamelCapsMethodName.NotCamelCaps" />
    </rule>

    <!-- Line length limit -->
    <rule ref="Generic.Files.LineLength">
        <properties>
            <property name="lineLimit" value="150" />
            <property name="ignoreComments" value="true" />
        </properties>
    </rule>
</ruleset>

PHPStan Static Analysis

Run static analysis:

vendor/bin/phpstan analyse

Configuration (phpstan.neon):

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

# 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 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:

# 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

<type>: <subject>

<body>

<footer>

Types:

• feat: - New feature
• fix: - Bug fix
• refactor: - Code restructuring
• test: - Adding tests
• docs: - Documentation
• style: - Code style changes

Example:

feat: Add medication allergy checking

Implements automatic checking of patient allergies when
prescribing medications. Shows warning if potential
conflict detected.

Closes #1234

Submitting Changes

Create Pull Request

1. Push your branch to your fork:

git push origin feature/your-feature-name

2. Create Pull Request on GitHub
   • Target the develop branch
   • Fill in the PR template
   • Link any related issues

Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] New tests added
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated

## Related Issues
Closes #issue_number

Pull Request Review

Your PR will be reviewed by core maintainers. They may:

• Request changes
• Ask questions
• Suggest improvements
• Approve and merge

Be responsive to feedback. PRs with no activity for 30 days may be closed.

Code Review Guidelines

When your code is reviewed, expect feedback on:

1. Functionality - Does it work as intended?
2. Tests - Are there adequate tests?
3. Code quality - Is it maintainable?
4. Security - Are there security implications?
5. Performance - Does it impact system performance?
6. Standards - Does it follow coding standards?

Database Changes

If your changes require database modifications:

Create Migration

# Generate migration file
php protected/yiic.php migrate create your_migration_name

Migration Structure

class m240101_120000_add_patient_field extends OEMigration
{
    public function up()
    {
        $this->addColumn('patient', 'new_field', 'varchar(255)');
    }

    public function down()
    {
        $this->dropColumn('patient', 'new_field');
    }
}

Migration Best Practices

1. Always provide down() - Migrations must be reversible
2. Test both up and down - Ensure migrations work in both directions
3. Use OEMigration - Provides OpenEyes-specific helpers
4. Document changes - Comment complex migrations
5. Seed data - Include necessary lookup data

Reporting Issues

Report bugs and feature requests through GitHub Issues:

https://github.com/AppertaFoundation/openeyes/issues/new

Issue Template

## Description
Clear description of the issue

## Steps to Reproduce
1. Go to...
2. Click on...
3. See error

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OpenEyes version:
- PHP version:
- Database version:
- Browser (if relevant):

## Screenshots
If applicable

## Additional Context
Any other relevant information

Support vs Issues

GitHub Issues are for bugs and feature requests only. No service level agreement exists for the open source project.

For support:

• Contact official implementation partners
• See openeyes.apperta.org for partner list

Documentation

If your changes affect user-facing features:

1. Update relevant documentation
2. Add code comments
3. Update PHPDoc blocks
4. Consider adding examples

Licensing

By contributing, you agree that your contributions will be licensed under:

GNU Affero General Public License v3.0 (AGPL-3.0)

All contributions must:

• Be your original work
• Not violate third-party rights
• Be compatible with AGPL-3.0

Community Guidelines

Be Respectful

• Use welcoming and inclusive language
• Respect differing viewpoints
• Accept constructive criticism gracefully
• Focus on what is best for the community

Be Professional

• Keep discussions on-topic
• Provide constructive feedback
• Help others learn and grow
• Lead by example

Getting Help

Contact Information

• Email: [e-mail]
• Twitter: @openeyes_oef
• Website: openeyes.apperta.org

Resources

• OpenEyes Website
• GitHub Repository
• Installation Wiki
• EyeDraw Repository

Release Process

1. Features merged to develop
2. Release branch created from develop
3. Testing and bug fixes on release branch
4. Release branch merged to master
5. Tagged with version number
6. Merged back to develop

Contributors don’t typically manage releases, but understanding the process helps with planning contributions.

Contributor Recognition

Contributions are recognized in:

• Git commit history
• Release notes
• Project credits

Thank you for contributing to OpenEyes!

Next Steps

Architecture

Understand the system architecture

Module Development

Learn to create modules