Contributing - OpenEyes

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 [email protected] 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

Fork the repository on GitHub
Clone your fork locally:

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

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

Follow existing patterns - Match the style of surrounding code
Use meaningful names - Variables, methods, and classes should be self-documenting
Comment complex logic - Explain why, not what
Keep methods short - Single responsibility principle
Write tests - All new code should have tests
Use type hints - Where possible in PHP 7.4+
Handle errors - Don’t ignore exceptions

Testing Requirements

All contributions must include appropriate tests.

Required Tests

Unit tests for individual classes/methods
Feature tests for user-facing functionality
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

Create feature branch from develop
Make your changes following coding standards
Write tests for new functionality
Run tests to ensure nothing breaks
Check code style with phpcs
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

Push your branch to your fork:

git push origin feature/your-feature-name

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:

Functionality - Does it work as intended?
Tests - Are there adequate tests?
Code quality - Is it maintainable?
Security - Are there security implications?
Performance - Does it impact system performance?
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

Always provide down() - Migrations must be reversible
Test both up and down - Ensure migrations work in both directions
Use OEMigration - Provides OpenEyes-specific helpers
Document changes - Comment complex migrations
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:

Update relevant documentation
Add code comments
Update PHPDoc blocks
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: [email protected]
Twitter: @openeyes_oef
Website: openeyes.apperta.org

Resources

Release Process

Features merged to develop
Release branch created from develop
Testing and bug fixes on release branch
Release branch merged to master
Tagged with version number
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

Get Started

User Guide

Clinical Modules

Administration

Development

​Before You Start

​Getting Started

​Repository Access

​Fork and Clone

​Git Workflow

​Branch Structure

​Creating a Feature Branch

​Branch Naming

​Coding Standards

​PHP CodeSniffer

​Code Style Rules

​PHPStan Static Analysis

​Best Practices

​Testing Requirements

​Required Tests

​Running Tests

​Test Requirements

​Making Changes

​Development Process

​Commit Messages

​Commit Message Format

​Submitting Changes

​Create Pull Request

​Pull Request Template

​Pull Request Review

​Code Review Guidelines

​Database Changes

​Create Migration

​Migration Structure

​Migration Best Practices

​Reporting Issues

​Issue Template

​Support vs Issues

​Documentation

​Licensing

​Community Guidelines

​Be Respectful

​Be Professional

​Getting Help

​Contact Information

​Resources

​Release Process

​Contributor Recognition

​Next Steps

Architecture

Module Development

Build docs developers (and LLMs) love

Before You Start

Getting Started

Repository Access

Fork and Clone

Git Workflow

Branch Structure

Creating a Feature Branch

Branch Naming

Coding Standards

PHP CodeSniffer

Code Style Rules

PHPStan Static Analysis

Best Practices

Testing Requirements

Required Tests

Running Tests

Test Requirements

Making Changes

Development Process

Commit Messages

Commit Message Format

Submitting Changes

Create Pull Request

Pull Request Template

Pull Request Review

Code Review Guidelines

Database Changes

Create Migration

Migration Structure

Migration Best Practices

Reporting Issues

Issue Template

Support vs Issues

Documentation

Licensing

Community Guidelines

Be Respectful

Be Professional

Getting Help

Contact Information

Resources

Release Process

Contributor Recognition

Next Steps