Skip to content

Latest commit

 

History

History
629 lines (535 loc) · 36.2 KB

CONTRIBUTING.md

File metadata and controls

629 lines (535 loc) · 36.2 KB

Thank you for your contribution. OpenEMR (and global healthcare) continues to get better because of people like you!

The maintainers of OpenEMR want to get your pull request in as seamlessly as possible, so please ensure your code is consistent with our development policies.

Commit Messages

OpenEMR uses Conventional Commits for all commits merged to master and rel-* branches. Your PR title must follow this format:

<type>(<scope>): <description>

Types

Type Description
feat New feature
fix Bug fix
docs Documentation only
style Code style (formatting, whitespace)
refactor Code refactoring (no feature/fix)
perf Performance improvement
test Adding/updating tests
build Build system or dependencies
ci CI configuration
chore Maintenance tasks
revert Revert a previous commit

Examples

  • feat(api): add PATCH support for patient resource
  • fix(calendar): correct date parsing for recurring events
  • docs(readme): update installation instructions
  • chore(deps): bump monolog/monolog from 3.9.0 to 3.10.0

Scopes

Scopes are optional but encouraged. Use them to indicate the area of the codebase affected (e.g., api, calendar, patient, billing, deps).

Breaking Changes

For breaking changes, add ! after the type/scope or include a BREAKING CHANGE: footer:

feat(api)!: change patient endpoint response format

BREAKING CHANGE: The patient endpoint now returns a different JSON structure.

Local Validation

If you use pre-commit, install hooks to validate locally:

pre-commit install --hook-type commit-msg  # Validates commit message format
pre-commit install                          # Enables all code quality hooks

The full pre-commit suite (.pre-commit-config.yaml) includes:

  • Trailing whitespace, line endings, JSON/YAML formatting
  • PHP syntax checking, phpcs, phpcbf, phpstan, rector
  • Composer validation and normalization

Code Quality on Host

If you have PHP and Node.js installed locally, you can run code quality checks without Docker:

# Run all PHP checks (phpcs, phpstan, rector)
composer code-quality

# Individual checks (these handle memory limits automatically)
composer phpstan          # Static analysis
composer phpcs            # Code style check
composer phpcbf           # Code style auto-fix
composer rector-check     # Code modernization (dry-run)

# JavaScript/CSS
npm run lint:js           # ESLint
npm run lint:js-fix       # ESLint auto-fix
npm run stylelint         # CSS/SCSS linting

These provide higher memory limits than Docker devtools and are what CI runs.

Isolated Tests (no Docker required)

Some tests run on the host without a database or Docker:

composer phpunit-isolated        # Run all isolated tests

This includes Twig template tests that verify compilation and rendering. If you modify a Twig template that has render test coverage, update the expected output fixtures:

composer update-twig-fixtures    # Regenerate fixture files

Review the diff before committing. See tests/Tests/Isolated/Common/Twig/fixtures/render/README.md for details.

Code Contributions (local development)

You will need a "local" version of OpenEMR to make changes to the source code. The easiest way to do this is with Docker:

Starting with OpenEMR Development Docker Environment

  1. Create your own fork of OpenEMR (you will need a GitHub account) and git clone it to your local machine.

  2. cd openemr/docker/development-easy

  3. Run docker compose up from your command line

    • When the build is done, you'll see the following message:
    openemr_1  | Love OpenEMR? You can now support the project via the open collective:
openemr_1  |  > https://opencollective.com/openemr/donate
openemr_1  |
openemr_1  | Starting cron daemon!
openemr_1  | Starting apache!

  4. Navigate to http://localhost:8300/ or https://localhost:9300/ to login as admin. Password is pass.

  5. If you wish to connect to the sql database, this docker environment provides the following 2 options:

    • Navigate to http://localhost:8310/ where you can login into phpMyAdmin.
    • Or you can directly connect to port 8320 via your favorite sql tool (Mysql Workbench etc.).
    • Use username/user: openemr, password: openemr .

  6. Make changes to any files on your local file system. Most changes will appear after a refresh of the page or iFrame you're working on.

    • For the Video Tutorials, click below:

      Getting Started Video Tutorial

      Getting Started Video Tutorial

    • An exception to this is if making changes to styling scripts in interface/themes/. In that case will need to clear web browser cache and run the following command to rebuild the theme files:

      docker compose exec openemr /root/devtools build-themes

  7. When you're done, it's best to clean up after yourself with docker compose down -v

    • If you don't want to build from scratch every time, just use docker compose down so your next docker compose up will use the cached volumes.

  8. To ensure you are using the most recent dockers, recommend running below set of commands intermittently:

    docker compose pull

  9. Submit a PR from your fork into openemr/openemr#master!

After You Submit

For first-time contributors: A maintainer must approve your PR before CI checks will run. This is a GitHub security measure for external contributors.

Automated checks include:

  • Conventional commit validation (PR title format)
  • PHP syntax, phpcs, phpstan, rector
  • Unit, API, E2E, and integration tests across multiple PHP/database versions
  • JavaScript tests, Docker linting, and more

See ci/README.md for details on the CI system.

Tip: During development, you can add Skip-Slow-Tests: true as a commit trailer to skip the full test matrix and get faster feedback from linting:

git commit --trailer "Skip-Slow-Tests: true" -m "fix: work in progress"

You must remove any Skip-Slow-Tests or skip-ci trailers before your PR can be merged.

Review process: A maintainer will review your PR. Please respond to feedback and push updates to the same branch—the PR will update automatically.

We look forward to your contribution...

Advanced Use of OpenEMR Development Docker Environment

The OpenEMR development docker environment has a very rich advanced feature set. See below Index for links to all the cool advanced stuff:

Index for Advanced Use of OpenEMR Development Docker Environment

  1. Xdebug and profiling
  2. API development and testing
  3. Testing other PHP versions
  4. Php syntax checking, psr12 checking, and automated testing
  5. Run the entire dev tool suite
  6. Run only all the automated tests
  7. Resetting OpenEMR and loading demo data
  8. Backup and restore OpenEMR data
  9. Send/receive snapshots
  10. Create and add random patient data
  11. Add multisite bank
  12. Turn on and turn off support for multisite feature in setup.php
  13. List the current multisite
  14. Change the database character set and collation
  15. Test ssl certificate and force/unforce https
  16. Place/remove testing sql ssl certificate and testing sql ssl client key/cert
  17. CouchDB integration
  18. LDAP integration
  19. Test webroot value

  1. Xdebug and profiling is supported for PHPStorm, VSCode and VSCodium.

    • For the Video Tutorial, click below:

      Getting Started Video Tutorial

    • Firefox/Chrome install xdebug helper add on and enable

    • PHPStorm Settings->Language & Frameworks->PHP->Debug

      • Start listening
      • Untoggle "Break at first line in PHP scripts"
      • Untoggle both settings that start with "Force Break at first line..."
      • See these images for more detail

    • VSCode and VSCodium

      • Listen for XDebug
      • Use this launch.json template

    • Make sure port 9003 is open on your host operating system

    • Profiling output can be found in /tmp directory in the docker. Following will list the profiling output files:

      docker compose exec openemr /root/devtools list-xdebug-profiles

    • To check Xdebug log:

      docker compose exec openemr /root/devtools xdebug-log

  2. API development and testing.

    • Swagger is including in OpenEMR to ease API documentation, development, and testing.
    • The following command will update the API documentation (derive documentation from _rest_routes.inc.php to swagger/openemr-api.yaml): 
      docker compose exec openemr /root/devtools build-api-docs
    • Can go to Swagger at https://localhost:9300/swagger where it is super easy to test the API:
      • First, click on 'Authorize' button.
      • Then click 'Select All' scopes.
      • Can then do the following from command line to get a client id and secret, which then can copy/paste into the fields: 
        docker compose exec openemr /root/devtools register-oauth2-client
      • Then click 'Authorize' button and follow the flow and before you know it, you will be authorized to test the api endpoints!
    • There is also a mechanism to allow use of the above Swagger tool with multisite.
      • Before going to the Swagger gui linked above, run the following command (after running below command, the Swagger gui will then be configured to work with the selected multisite): 
        docker compose exec openemr /root/devtools set-swagger-to-multisite <multisite-name>
      • To collect a client id and secret for the selected multisite, can then do: 
        docker compose exec openemr /root/devtools register-oauth2-client <multisite-name>
      • When done testing with Swagger on the selected multisite, recommend setting swagger back to the default multisite to avoid changes to the swagger configuration script showing up in your local git repository: 
        docker compose exec openemr /root/devtools set-swagger-to-multisite
    • There is also a dev tool to make it easy to test the API on the online OpenEMR demo farm. For example, what if you wanted to test the API at https://eleven.openemr.io/a/openemr:
      • Go to https://eleven.openemr.io/a/openemr/swagger and follow the Swagger gui flow above. The following command can be used to get a client id and secret from that online demo: 
        docker compose exec openemr /root/devtools register-oauth2-client-demo https://eleven.openemr.io/a/openemr

  3. Testing other PHP versions.

    • The standard flex docker used in the easy development environments is PHP 8.4. This can be modified by changing the image (image: openemr/openemr:flex) used in the docker-compose.yml script. To use PHP 8.2, then just need to change it to image: openemr/openemr:flex-3.22-php-8.2. To use PHP 8.3 then change it to image: openemr/openemr:flex-3.22-php-8.3.

  4. Php syntax checking, psr12 checking, and automated testing.

    • To check PHP error logs: 
      docker compose exec openemr /root/devtools php-log
    • To create a report of PSR12 code styling issues (this takes several minutes): 
      docker compose exec openemr /root/devtools psr12-report
    • To fix PSR12 code styling issues (this takes several minutes): 
      docker compose exec openemr /root/devtools psr12-fix
    • To create a report of theme styling issues: 
      docker compose exec openemr /root/devtools lint-themes-report
    • To fix theme styling issues: 
      docker compose exec openemr /root/devtools lint-themes-fix
    • To check PHP parsing errors (this takes several minutes): 
      docker compose exec openemr /root/devtools php-parserror
    • To dry run Rector changes: 
      docker compose exec openemr /root/devtools rector-dry-run
    • To process Rector changes: 
      docker compose exec openemr /root/devtools rector-process
    • To run unit testing: 
      docker compose exec openemr /root/devtools unit-test
    • To run api testing: 
      docker compose exec openemr /root/devtools api-test
    • To run e2e testing: 
      docker compose exec openemr /root/devtools e2e-test
      • (You can actually view the e2e tests in real-time by going to http://localhost:7900 with password 'openemr123'.)
    • To run services testing: 
      docker compose exec openemr /root/devtools services-test
    • To run fixtures testing: 
      docker compose exec openemr /root/devtools fixtures-test
    • To run validators testing: 
      docker compose exec openemr /root/devtools validators-test
    • To run controllers testing: 
      docker compose exec openemr /root/devtools controllers-test
    • To run common testing: 
      docker compose exec openemr /root/devtools common-test

  5. Run the entire dev tool suite (PSR12 fix, lint themes fix, PHP parse error, unit/API/e2e/services/fixtures/validators/controllers/common tests) in one command, run

    docker compose exec openemr /root/devtools clean-sweep

  6. Run only all the automated tests (unit/API/e2e/services/fixtures/validators/controllers/common tests) in one command, run

    docker compose exec openemr /root/devtools clean-sweep-tests

  7. Resetting OpenEMR and loading demo data.

    • For the Video Tutorial, click below:

      Resetting and Demo Data Video Tutorial

    • To reset OpenEMR only (then can reinstall manually via setup.php in web browser):

      docker compose exec openemr /root/devtools dev-reset
      • When running setup.php, need to use mysql for 'Server Host', root for 'Root Password', and % for 'User Hostname'.

    • To reset and reinstall OpenEMR:

      docker compose exec openemr /root/devtools dev-reset-install

    • To reset and reinstall OpenEMR with demo data (this includes several users with access controls setup in addition to patient portal logins. See HERE for those credentials.):

      docker compose exec openemr /root/devtools dev-reset-install-demodata
      • hint: this is also a great way to test any changes a developer has made to the sql upgrade stuff (ie. such as sql/5_0_2-to-6_0_0_upgrade.sql)

  8. Backup and restore OpenEMR data (database and data on drive) via snapshots.

    docker compose exec openemr /root/devtools backup example
    • Restore from a snapshot (using example below, but can use any alphanumeric identifier) 
      docker compose exec openemr /root/devtools restore example
    • To list the snapshots 
      docker compose exec openemr /root/devtools list-snapshots

  9. Send/receive snapshots (via capsules) that are created above in item 8.

    • For the Video Tutorial, click below:

      Snapshots and Capsules Video Tutorial

    • Here is how to grab a capsule from the docker, which can then store or share with friends.

      • List the capsules: 
        docker compose exec openemr /root/devtools list-capsules
      • Copy the capsule from the docker to your current directory (using example.tgz below): 
        docker compose cp openemr:/snapshots/example.tgz .

    • Here is how to send a capsule into the docker.

      • Copy the capsule from current directory into the docker (using example.tgz below): 
        docker compose cp example.tgz openemr:/snapshots/
      • Restore from the new shiny snapshot (using example below): 
        docker compose exec openemr /root/devtools restore example
      • Ensure run upgrade to ensure will work with current version OpenEMR: 
        docker compose exec openemr /root/devtools upgrade 5.0.2

  10. Create and add random patient data. This will use synthea to create random patients that are then imported into OpenEMR. You can choose the number of patients. Note that each patient will take several seconds.

    • For the Video Tutorial, click below:

      Creating Random Patients Video Tutorial

    • Create and add 100 random patients (defaults to development mode set to true, which is set be default to true; development mode will markedly improve performance by bypassing the import of the ccda document and bypassing the use of the audit_master and audit_details tables and will directly import the new patient data from the ccda. Note this should never be done on sites that already contain real data/use, and it will also turn off the audit log during the import.):

      docker compose exec openemr /root/devtools import-random-patients 100

      or

      docker compose exec openemr /root/devtools import-random-patients 100 true

    • Create and add 100 random patients (with development mode set to false)

      docker compose exec openemr /root/devtools import-random-patients 100 false

  11. Create a bank of multisites with selected number of multisites that are all labelled from run1..runx. It will clone from the default instance. This can be helpful for testing of multisites and other larger scale testing.

    • Create 5 multisites (will be run1, run2, run3, run4, run5): 
      docker compose exec openemr /root/devtools generate-multisite-bank 5

  12. Turn on and turn off support for multisite feature (to allow setting up multisites in setup.php script).

    • Turn on support for multisite: 
      docker compose exec openemr /root/devtools enable-multisite
    • Turn off support for multisite: 
      docker compose exec openemr /root/devtools disable-multisite

  13. The available multsites can be listed via following command:

    docker compose exec openemr /root/devtools list-multisites

  14. Change the database character set and collation (character set is the encoding that is used to store data in the database; collation are a set of rules that the database uses to sort the stored data).

    • Best to demonstrate this devtool with examples.
      • Set character set to utf8mb4 and collation to utf8mb4_general_ci (this is default for OpenEMR 6 and higher): 
        docker compose exec openemr /root/devtools change-encoding-collation utf8mb4 utf8mb4_general_ci
      • Set character set to utf8mb4 and collation to utf8mb4_unicode_ci: 
        docker compose exec openemr /root/devtools change-encoding-collation utf8mb4 utf8mb4_unicode_ci
      • Set character set to utf8mb4 and collation to utf8mb4_vietnamese_ci: 
        docker compose exec openemr /root/devtools change-encoding-collation utf8mb4 utf8mb4_vietnamese_ci
      • Set character set to utf8 and collation to utf8_general_ci (this is default for OpenEMR 5 and lower): 
        docker compose exec openemr /root/devtools change-encoding-collation utf8 utf8_general_ci

  15. Test ssl certificate (to test client based certificates and revert back to default self signed certificate) and force/unforce https.

    • To test client based certificates, create a zip package of the certificate in OpenEMR at Administration->System->Certificates. Then can import this zip package (example ssl.zip) into the docker via: 
      docker compose cp ssl.zip openemr:/certs/
    • To list the available certificate packages on docker: 
      docker compose exec openemr /root/devtools list-client-certs
    • To install and configure a certificate package (example ssl): 
      docker compose exec openemr /root/devtools setup-client-cert ssl
    • To revert back to self-signed certificates (ie. revert the changes required for client based certificates): 
      docker compose exec openemr /root/devtools on-self-signed-cert
    • To force https in apache script via redirect: 
      docker compose exec openemr /root/devtools force-https
    • To revert the changes that forced https in apache script: 
      docker compose exec openemr /root/devtools un-force-https

  16. Place/remove testing sql ssl certificate and testing sql ssl client key/cert.

    • Place the testing sql ssl CA cert: 
      docker compose exec openemr /root/devtools sql-ssl
    • Remove the testing sql ssl CA cert: 
      docker compose exec openemr /root/devtools sql-ssl-off
    • Place the testing sql ssl CA cert and testing sql ssl client key/cert: 
      docker compose exec openemr /root/devtools sql-ssl-client
    • Remove the testing sql ssl CA cert and testing sql ssl client key/cert: 
      docker compose exec openemr /root/devtools sql-ssl-client-off

  17. CouchDB integration.

    • In OpenEMR, CouchDB is an option for the patients document storage. For this reason, a CouchDB docker is included in this OpenEMR docker development environment. You can visit the CouchDB GUI directly via http://localhost:5984/_utils/ or https://localhost:6984/_utils/ with username admin and password password. You can configure OpenEMR to use this CouchDB docker for patient document storage in OpenEMR at Administration->Globals->Documents:
      • Document Storage Method->CouchDB
    • After running the following devtools, 'dev-reset', 'dev-install', 'dev-reset-install', 'dev-reset-install-demodata', 'restore-snapshot', then need to restart the couchdb docker via the following command: 
      docker compose restart couchdb
    • Developer tools to place/remove testing couchdb ssl certificate and testing couchdb ssl client key/cert.
      • Place the testing couchdb ssl CA cert: 
        docker compose exec openemr /root/devtools couchdb-ssl
      • Remove the testing couchdb ssl CA cert: 
        docker compose exec openemr /root/devtools couchdb-ssl-off
      • Place the testing couchdb ssl CA cert and testing couchdb ssl client key/cert: 
        docker compose exec openemr /root/devtools couchdb-ssl-client
      • Remove the testing couchdb ssl CA cert and testing couchdb ssl client key/cert: 
        docker compose exec openemr /root/devtools couchdb-ssl-client-off

  18. LDAP integration.

    • In OpenEMR, LDAP is an option for authentication. If this is turned on, then this will be supported for the admin user, which will use the following password: admin
    • Turn on LDAP: 
      docker compose exec openemr /root/devtools enable-ldap
    • Turn off LDAP: 
      docker compose exec openemr /root/devtools disable-ldap
    • Developer tools to place/remove testing ldap tls/ssl certificate and testing ldap tls/ssl client key/cert.
      • Place the testing ldap tls/ssl CA cert: 
        docker compose exec openemr /root/devtools ldap-ssl
      • Remove the testing ldap tls/ssl CA cert: 
        docker compose exec openemr /root/devtools ldap-ssl-off
      • Place the testing ldap tls/ssl CA cert and testing ldap tls/ssl client key/cert: 
        docker compose exec openemr /root/devtools ldap-ssl-client
      • Remove the testing ldap tls/ssl CA cert and testing ldap tls/ssl client key/cert: 
        docker compose exec openemr /root/devtools ldap-ssl-client-off

  19. Test webroot value.

    • The default setup of the docker development environments are with a blank webroot, however, it is a good idea to also test with a webroot setting. There is an option to set the webroot to openemr.
    • Note this dev tool requires the use of the openemr-cmd script, which is discussed above and can find instructions to install and use openemr-cmd script at install openemr-cmd.
    • Set webroot to blank: 
      openemr-cmd change-webroot-blank
    • Set webroot to openemr: 
      openemr-cmd change-webroot-openemr

Non-docker Use

If you do not want to use Docker, you can always install OpenEMR directly on your local environment. This will require installing additional dependencies for your operating system. For more info see OpenEMR Development Versions on the wiki.

Financial contributions

We also welcome financial contributions in full transparency on our open collective. Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.

Credits

Contributors

Thank you to all the people who have already contributed to openemr!

Backers

Thank you to all our backers! [Become a backer]

Sponsors

Thank you to all our sponsors! (please ask your company to also support this open source project by becoming a sponsor)