CONTRIBUTING.md

   1 Thank you for your contribution. OpenEMR (and global healthcare) continues to get better because of people like you!
   2
   3 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](https://open-emr.org/wiki/index.php/Development_Policies).
   4
   5 ## Code Contributions (local development)
   6
   7 You will need a "local" version of OpenEMR to make changes to the source code. The easiest way to do this is with [Docker](https://hub.docker.com/r/openemr/openemr/):
   8
   9 1. [Create your own fork of OpenEMR](https://github.com/openemr/openemr/fork) (you will need a GitHub account) and `git clone` it to your local machine.
  10         - If you want to set up the base services(e.g. git, docker, docker-compose, openemr-cmd, minkube and kubectl) easily, please try [openemr-env-installer](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-env-installer)
  11     - It's best to also add an `upstream` origin to keep your local fork up to date. [Check out this guide](https://oneemptymind.wordpress.com/2018/07/11/keeping-a-fork-up-to-date/) for more info.
  12         - If you haven't already, [install git](https://git-scm.com/downloads) for your system
  13 2. `cd openemr/docker/development-easy` (if you are running this on Raspberry Pi, then instead do `cd openemr/docker/development-easy-arm32` or `cd openemr/docker/development-easy-arm64`)
  14     - If you haven't already, [install Docker](https://docs.docker.com/install/) and [install compose](https://docs.docker.com/compose/install/) for your system
  15         - If you want to troubleshoot with the below steps easier, please also [install openemr-cmd](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-cmd) for your system
  16     - If you want to monitor and easily manage the docker environment, please also [install openemr-monitor](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-monitor) and [install portainer](https://github.com/openemr/openemr-devops/tree/master/utilities/portainer) for your system
  17         - If you want to migrate the running docker environment, please try [openemr-env-migrator](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-env-migrator)
  18         - If you want to set up with orchestration tool, please try [OpenEMR Kubernetes Orchestrations](https://github.com/openemr/openemr-devops/tree/master/kubernetes/minikube)
  19 3. Run `docker-compose up` from your command line
  20     - When the build is done, you'll see the following message:
  21     ```sh
  22     openemr_1  | Love OpenEMR? You can now support the project via the open collective:
  23     openemr_1  |  > https://opencollective.com/openemr/donate
  24     openemr_1  |
  25     openemr_1  | Starting cron daemon!
  26     openemr_1  | Starting apache!
  27     ```
  28 4. Navigate to `http://localhost:8300/` to login as `admin`. Password is `pass`.
  29 5. 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.
  30     - 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:
  31       ```sh
  32       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools build-themes'
  33       ```
  34 6. If you wish to connect to the sql database, this docker environment provides the following 2 options:
  35     - Navigate to `http://localhost:8310/` where you can login into phpMyAdmin.
  36     - Or you can directly connect to port 8320 via your favorite sql tool (Mysql Workbench etc.).
  37     - Use `username/user`: openemr, `password`: openemr .
  38 7. Developer tools for php syntax checking, psr12 checking, and automated testing.
  39     - To check PHP error logs:
  40       ```sh
  41       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools php-log'
  42       ```
  43     - To create a report of PSR12 code styling issues (this takes several minutes):
  44       ```sh
  45       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools psr12-report'
  46       ```
  47     - To fix PSR12 code styling issues (this takes several minutes):
  48       ```sh
  49       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools psr12-fix'
  50       ```
  51     - To create a report of theme styling issues:
  52       ```sh
  53       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools lint-themes-report'
  54       ```
  55     - To fix theme styling issues:
  56       ```sh
  57       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools lint-themes-fix'
  58       ```
  59     - To check PHP parsing errors (this takes several minutes):
  60       ```sh
  61       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools php-parserror'
  62       ```
  63     - To run unit testing:
  64       ```sh
  65       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools unit-test'
  66       ```
  67     - To run api testing:
  68       ```sh
  69       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools api-test'
  70       ```
  71     - To run e2e testing:
  72       ```sh
  73       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools e2e-test'
  74       ```
  75     - To run services testing:
  76       ```sh
  77       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools services-test'
  78       ```
  79     - To run fixtures testing:
  80       ```sh
  81       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools fixtures-test'
  82       ```
  83     - To run validators testing:
  84       ```sh
  85       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools validators-test'
  86       ```
  87     - To run controllers testing:
  88       ```sh
  89       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools controllers-test'
  90       ```
  91     - To run common testing:
  92       ```sh
  93       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools common-test'
  94       ```
  95 8. To 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
  96     ```sh
  97     docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools clean-sweep'
  98     ```
  99 9. To run only all the automated tests (unit/API/e2e/services/fixtures/validators/controllers/common tests) in one command, run
 100     ```sh
 101     docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools clean-sweep-tests'
 102     ```
 103 10. Developer tools to reset openemr and to load demo data.
 104     - To reset OpenEMR only (then can reinstall manually via setup.php in web browser):
 105       ```sh
 106       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset'
 107       ```
 108         - When running setup.php, need to use `mysql` for 'Server Host', `root` for 'Root Password', and `%` for 'User Hostname'.
 109     - To reset and reinstall OpenEMR:
 110       ```sh
 111       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset-install'
 112       ```
 113     - 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](https://www.open-emr.org/wiki/index.php/Development_Demo#Demo_Credentials).):
 114       ```sh
 115       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset-install-demodata'
 116       ```
 117         - 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)
 118 11. Developer tools to backup and restore OpenEMR data (database and data on drive) via snapshots.
 119     - Create a backup snapshot (using `example` below, but can use any alphanumeric identifier):
 120       ```sh
 121       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools backup example'
 122       ```
 123     - Restore from a snapshot (using `example` below, but can use any alphanumeric identifier)
 124       ```sh
 125       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools restore example'
 126       ```
 127     - To list the snapshots
 128       ```sh
 129       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-snapshots'
 130       ```
 131 12. Developer tools to send/receive snapshots (via capsules) that are created above in item 11.
 132     - Here is how to grab a capsule from the docker, which can then store or share with friends.
 133         - List the capsules:
 134           ```sh
 135           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-capsules'
 136           ```
 137         - Copy the capsule from the docker to your current directory (using `example.tgz` below):
 138           ```sh
 139           docker cp $(docker ps | grep _openemr | cut -f 1 -d " "):/snapshots/example.tgz .
 140           ```
 141     - Here is how to send a capsule into the docker.
 142         - Copy the capsule from current directory into the docker (using `example.tgz` below):
 143           ```sh
 144           docker cp example.tgz $(docker ps | grep _openemr | cut -f 1 -d " "):/snapshots/
 145           ```
 146         - Restore from the new shiny snapshot (using `example` below):
 147           ```sh
 148           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools restore example'
 149           ```
 150         - Ensure run upgrade to ensure will work with current version OpenEMR:
 151           ```sh
 152           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools upgrade 5.0.2'
 153           ```
 154 13. Developer tools to turn on and turn off support for multisite feature.
 155     - Turn on support for multisite:
 156       ```sh
 157       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools enable-multisite'
 158       ```
 159     - Turn off support for multisite:
 160       ```sh
 161       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools disable-multisite'
 162       ```
 163 14. Developer tool to 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).
 164     - Best to demonstrate this devtool with examples.
 165         - Set character set to utf8mb4 and collation to utf8mb4_general_ci (this is default for OpenEMR 6 and higher):
 166           ```sh
 167           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools change-encoding-collation utf8mb4 utf8mb4_general_ci'
 168           ```
 169         - Set character set to utf8mb4 and collation to utf8mb4_unicode_ci:
 170           ```sh
 171           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools change-encoding-collation utf8mb4 utf8mb4_unicode_ci'
 172           ```
 173         - Set character set to utf8mb4 and collation to utf8mb4_vietnamese_ci:
 174           ```sh
 175           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools change-encoding-collation utf8mb4 utf8mb4_vietnamese_ci'
 176           ```
 177         - Set character set to utf8 and collation to utf8_general_ci (this is default for OpenEMR 5 and lower):
 178           ```sh
 179           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools change-encoding-collation utf8 utf8_general_ci'
 180           ```
 181 15. Developer tools to test ssl certificate (to test client based certificates and revert back to default self signed certificate) and force/unforce https.
 182     - 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:
 183       ```sh
 184       docker cp ssl.zip $(docker ps | grep _openemr | cut -f 1 -d " "):/certs/
 185       ```
 186     - To list the available certificate packages on docker:
 187       ```sh
 188       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-client-certs'
 189       ```
 190     - To install and configure a certificate package (example `ssl`):
 191       ```sh
 192       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools setup-client-cert ssl'
 193       ```
 194     - To revert back to selfsigned certicates (ie. revert the changes required for client based certificates):
 195       ```sh
 196       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools on-self-signed-cert'
 197       ```
 198     - To force https in apache script via redirect:
 199       ```sh
 200       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools force-https'
 201       ```
 202     - To revert the changes that forced https in apache script:
 203       ```sh
 204       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools un-force-https'
 205       ```
 206 16. Developer tools to place/remove testing sql ssl certificate and testing sql ssl client key/cert.
 207     - Place the testing sql ssl CA cert:
 208       ```sh
 209       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools sql-ssl'
 210       ```
 211     - Remove the testing sql ssl CA cert:
 212       ```sh
 213       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools sql-ssl-off'
 214       ```
 215     - Place the testing sql ssl CA cert and testing sql ssl client key/cert:
 216       ```sh
 217       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools sql-ssl-client'
 218       ```
 219     - Remove the testing sql ssl CA cert and testing sql ssl client key/cert:
 220       ```sh
 221       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools sql-ssl-client-off'
 222       ```
 223 17. CouchDB integration.
 224     - 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:
 225         - Document Storage Method->CouchDB
 226     - 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:
 227         ```sh
 228         docker restart $(docker ps | grep _couchdb_1 | cut -f 1 -d " ")
 229         ```
 230     - Developer tools to place/remove testing couchdb ssl certificate and testing couchdb ssl client key/cert.
 231         - Place the testing couchdb ssl CA cert:
 232           ```sh
 233           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools couchdb-ssl'
 234           ```
 235         - Remove the testing couchdb ssl CA cert:
 236           ```sh
 237           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools couchdb-ssl-off'
 238           ```
 239         - Place the testing couchdb ssl CA cert and testing couchdb ssl client key/cert:
 240           ```sh
 241           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools couchdb-ssl-client'
 242           ```
 243         - Remove the testing couchdb ssl CA cert and testing couchdb ssl client key/cert:
 244           ```sh
 245           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools couchdb-ssl-client-off'
 246           ```
 247 18. LDAP integration.
 248     - 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`
 249     - Turn on LDAP:
 250       ```sh
 251       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools enable-ldap'
 252       ```
 253     - Turn off LDAP:
 254       ```sh
 255       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools disable-ldap'
 256       ```
 257     - Developer tools to place/remove testing ldap tls/ssl certificate and testing ldap tls/ssl client key/cert.
 258         - Place the testing ldap tls/ssl CA cert:
 259           ```sh
 260           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools ldap-ssl'
 261           ```
 262         - Remove the testing ldap tls/ssl CA cert:
 263           ```sh
 264           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools ldap-ssl-off'
 265           ```
 266         - Place the testing ldap tls/ssl CA cert and testing ldap tls/ssl client key/cert:
 267           ```sh
 268           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools ldap-ssl-client'
 269           ```
 270         - Remove the testing ldap tls/ssl CA cert and testing ldap tls/ssl client key/cert:
 271           ```sh
 272           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools ldap-ssl-client-off'
 273           ```
 274 19. Xdebug and profiling is also supported for PHPStorm.
 275     - Firefox install xdebug helper add on (configure for PHPSTORM)
 276     - PHPStorm Settings->Language & Frameworks->PHP->Debug
 277         - Start listening
 278         - Untoggle "Break at first line in PHP scripts"
 279         - Untoggle both settings that start with "Force Break at first line..."
 280     - Make sure port 9000 is open on your host operating system
 281     - Profiling output can be found in /tmp directory in the docker. Following will list the profiling output files:
 282       ```sh
 283       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-xdebug-profiles'
 284       ```
 285     - To check Xdebug log:
 286       ```sh
 287       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools xdebug-log'
 288       ```
 289 20. When you're done, it's best to clean up after yourself with `docker-compose down -v`
 290     - 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.
 291 21. To ensure you are using the most recent dockers, recommend running below set of commands intermittently:
 292     ```console
 293     docker pull openemr/openemr:flex
 294     docker pull mariadb:10.5
 295     docker pull phpmyadmin/phpmyadmin
 296     docker pull couchdb
 297     docker pull openemr/dev-ldap:easy
 298     ```
 299 22. [Submit a PR](https://github.com/openemr/openemr/compare) from your fork into `openemr/openemr#master`!
 300
 301 We look forward to your contribution...
 302
 303 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](https://open-emr.org/wiki/index.php/OpenEMR_Installation_Guides#OpenEMR_Development_Versions) on the wiki.
 304
 305 ## Financial contributions
 306
 307 We also welcome financial contributions in full transparency on our [open collective](https://opencollective.com/openemr).
 308 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.
 309
 310 ## Credits
 311
 312 ### Contributors
 313
 314 Thank you to all the people who have already contributed to openemr!
 315 <a href="https://github.com/openemr/openemr/graphs/contributors"><img src="https://opencollective.com/openemr/contributors.svg?width=890" /></a>
 316
 317 ### Backers
 318
 319 Thank you to all our backers! [[Become a backer](https://opencollective.com/openemr#backer)]
 320
 321 <a href="https://opencollective.com/openemr#backers" target="_blank"><img src="https://opencollective.com/openemr/backers.svg?width=890"></a>
 322
 323 ### Sponsors
 324
 325 Thank you to all our sponsors! (please ask your company to also support this open source project by [becoming a sponsor](https://opencollective.com/openemr#sponsor))
 326
 327 <a href="https://opencollective.com/openemr/sponsor/0/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/0/avatar.svg"></a>
 328 <a href="https://opencollective.com/openemr/sponsor/1/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/1/avatar.svg"></a>
 329 <a href="https://opencollective.com/openemr/sponsor/2/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/2/avatar.svg"></a>
 330 <a href="https://opencollective.com/openemr/sponsor/3/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/3/avatar.svg"></a>
 331 <a href="https://opencollective.com/openemr/sponsor/4/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/4/avatar.svg"></a>
 332 <a href="https://opencollective.com/openemr/sponsor/5/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/5/avatar.svg"></a>
 333 <a href="https://opencollective.com/openemr/sponsor/6/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/6/avatar.svg"></a>
 334 <a href="https://opencollective.com/openemr/sponsor/7/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/7/avatar.svg"></a>
 335 <a href="https://opencollective.com/openemr/sponsor/8/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/8/avatar.svg"></a>
 336 <a href="https://opencollective.com/openemr/sponsor/9/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/9/avatar.svg"></a>