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     - 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.
  11 2. `cd openemr` (the directory you cloned the code into)
  12     - If you haven't already, [install Docker](https://docs.docker.com/install/) for your system
  13 3. Run `docker-compose up` from your command line
  14     - When the build is done, you'll see the following message:
  15     ```sh
  16     openemr_1  | Love OpenEMR? You can now support the project via the open collective:
  17     openemr_1  |  > https://opencollective.com/openemr/donate
  18     openemr_1  |
  19     openemr_1  | Starting cron daemon!
  20     openemr_1  | Starting apache!
  21     ```
  22 4. Navigate to `http://localhost:8300/` to login as `admin`. Password is `pass`.
  23 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.
  24     - 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:
  25       ```sh
  26       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools build-themes'
  27       ```
  28 6. If you wish to connect to the sql database, this docker environment provides the following 2 options:
  29     - Navigate to `http://localhost:8310/` where you can login into phpMyAdmin.
  30     - Or you can directly connect to port 8320 via your favorite sql tool (Mysql Workbench etc.).
  31     - Use `username/user`: openemr, `password`: openemr .
  32 7. Developer tools for php syntax checking, psr12 checking, and automated testing.
  33     - To check PHP error logs:
  34       ```sh
  35       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools php-log'
  36       ```
  37     - To create a report of PSR12 code styling issues (this takes several minutes):
  38       ```sh
  39       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools psr12-report'
  40       ```
  41     - To fix PSR12 code styling issues (this takes several minutes):
  42       ```sh
  43       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools psr12-fix'
  44       ```
  45     - To create a report of theme styling issues:
  46       ```sh
  47       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools lint-themes-report'
  48       ```
  49     - To fix theme styling issues:
  50       ```sh
  51       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools lint-themes-fix'
  52       ```
  53     - To check PHP parsing errors (this takes several minutes):
  54       ```sh
  55       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools php-parserror'
  56       ```
  57     - To run unit testing:
  58       ```sh
  59       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools unit-test'
  60       ```
  61     - To run api testing:
  62       ```sh
  63       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools api-test'
  64       ```
  65     - To run e2e testing:
  66       ```sh
  67       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools e2e-test'
  68       ```
  69     - To run services testing:
  70       ```sh
  71       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools services-test'
  72       ```
  73     - To run fixtures testing:
  74       ```sh
  75       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools fixtures-test'
  76       ```
  77     - To run validators testing:
  78       ```sh
  79       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools validators-test'
  80       ```
  81     - To run controllers testing:
  82       ```sh
  83       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools controllers-test'
  84       ```
  85     - To run common testing:
  86       ```sh
  87       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools common-test'
  88       ```
  89 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
  90     ```sh
  91     docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools clean-sweep'
  92     ```
  93 9. To run only all the automated tests (unit/API/e2e/services/fixtures/validators/controllers/common tests) in one command, run
  94     ```sh
  95     docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools clean-sweep-tests'
  96     ```
  97 10. Developer tools to reset openemr and to load demo data.
  98     - To reset OpenEMR only (then can reinstall manually via setup.php in web browser):
  99       ```sh
 100       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset'
 101       ```
 102         - When running setup.php, need to use `mysql` for 'Server Host', `root` for 'Root Password', and `%` for 'User Hostname'.
 103     - To reset and reinstall OpenEMR:
 104       ```sh
 105       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset-install'
 106       ```
 107     - 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).):
 108       ```sh
 109       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset-install-demodata'
 110       ```
 111         - 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)
 112 11. Developer tools to turn on and turn off support for multisite feature.
 113     - Turn on support for multisite:
 114       ```sh
 115       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools enable-multisite'
 116       ```
 117     - Turn off support for multisite:
 118       ```sh
 119       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools disable-multisite'
 120       ```
 121 12. Xdebug and profiling is also supported for PHPStorm.
 122     - Firefox install xdebug helper add on (configure for PHPSTORM)
 123     - PHPStorm Settings->Language & Frameworks->PHP->Debug
 124         - Start listening
 125         - Untoggle "Break at first line in PHP scripts"
 126         - Untoggle both settings that start with "Force Break at first line..."
 127      - Make sure port 9000 is open on your host operating system
 128      - Profiling output can be found in /tmp directory in the docker
 129 13. When you're done, it's best to clean up after yourself with `docker-compose down -v`
 130     - 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.
 131 14. [Submit a PR](https://github.com/openemr/openemr/compare) from your fork into `openemr/openemr#master`!
 132
 133 We look forward to your contribution...
 134
 135 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.
 136
 137 ## Financial contributions
 138
 139 We also welcome financial contributions in full transparency on our [open collective](https://opencollective.com/openemr).
 140 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.
 141
 142 ## Credits
 143
 144 ### Contributors
 145
 146 Thank you to all the people who have already contributed to openemr!
 147 <a href="https://github.com/openemr/openemr/graphs/contributors"><img src="https://opencollective.com/openemr/contributors.svg?width=890" /></a>
 148
 149 ### Backers
 150
 151 Thank you to all our backers! [[Become a backer](https://opencollective.com/openemr#backer)]
 152
 153 <a href="https://opencollective.com/openemr#backers" target="_blank"><img src="https://opencollective.com/openemr/backers.svg?width=890"></a>
 154
 155 ### Sponsors
 156
 157 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))
 158
 159 <a href="https://opencollective.com/openemr/sponsor/0/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/0/avatar.svg"></a>
 160 <a href="https://opencollective.com/openemr/sponsor/1/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/1/avatar.svg"></a>
 161 <a href="https://opencollective.com/openemr/sponsor/2/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/2/avatar.svg"></a>
 162 <a href="https://opencollective.com/openemr/sponsor/3/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/3/avatar.svg"></a>
 163 <a href="https://opencollective.com/openemr/sponsor/4/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/4/avatar.svg"></a>
 164 <a href="https://opencollective.com/openemr/sponsor/5/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/5/avatar.svg"></a>
 165 <a href="https://opencollective.com/openemr/sponsor/6/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/6/avatar.svg"></a>
 166 <a href="https://opencollective.com/openemr/sponsor/7/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/7/avatar.svg"></a>
 167 <a href="https://opencollective.com/openemr/sponsor/8/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/8/avatar.svg"></a>
 168 <a href="https://opencollective.com/openemr/sponsor/9/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/9/avatar.svg"></a>