Updated dev install and release docs

RELEASES.md

@@ -1,29 +1,35 @@
 RELEASES
 --------
 
-Releases are partially automated in BHIMA.  This document is a checklist of things that need to be done
-before a release and the steps to creating a new release.
+Releases are partially automated in BHIMA.  This document is a checklist of things that need to be done before a release and the steps to creating a new release.
 
-1. Make a new branch called `release-next` that is based on `upstream/master` to do your release on.  If one exists on upstream, remove it first.
-2. Run `yarn` to ensure you have the latest dependencies.
-3. (Optional, best practice) Test the latest migration script on a production database. (*)
-4. (Optional, best practice) Build the application in production mode with `NODE_ENV=production yarn build`.
-5. Determine the version number for the next version. (v1.X.Y)
-6. Create a new folder in the `server/models/migrations/` directory to hold the migration file with the format `v1.A.B-v1.X.Y` where `1.A.B` is the current version and `v1.X.Y` is the next version.
-7. Move the `server/models/migrations/next/migrate.sql` file to the directory created in the above step.
-8. Create a blank `migrate.sql` file in `server/models/migrations/next/`.
-9. Commit updated files (git commit ...)
-10. Make sure your personal GITHUB_TOKEN environment variable is defined 
+The directions below assume you are working in a development environment based on a fork of the main BHIMA repository on github.
+
+1. Checkout Bhima 'master' from your fork of https://github.com/IMA-WorldHealth/bhima
+2. Do `git pull` to make sure it is up-to-date.
+3. Create a new branch called `release-next` (for example) that is based on the upstream repo to do your release with.  If one exists on upstream, remove it first.  For example, if the main BHIMA githup repo is called `upstream` in your local development setup, do:
+  - `git checkout -b release-next upstream/master`
+4. Run `yarn` to ensure you have the latest dependencies.
+5. (Optional, best practice) Test the latest migration script on a production database. (See * below)
+6. Build the application in production mode to make sure the build works correctly.
+  - `NODE_ENV=production yarn build`
+7. Determine the version number for the next version (eg, `v1.X.Y`)
+8. Create a new folder in the `server/models/migrations/` directory to hold the migration file with the format `v1.A.B-v1.X.Y` where `1.A.B` is the current version and `v1.X.Y` is the next version.
+9. Move the `server/models/migrations/next/migrate.sql` file to the directory created in the previous step.
+10. Create an empty `migrate.sql` file in `server/models/migrations/next/`.  You may insert a comment at the top of the file including the name of the new release version.
+11. Commit any updated files (`git commit ...`)
+12. Make sure your personal GITHUB_TOKEN environment variable is defined
     (assuming you have permissions to update the main BHIMA repository.  [See Github instructions for this.](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
-11. Run `yarn release` and follow the options.
-12. Verify the release was created and that the binary <version>.tar.gz file
+13. Run `yarn release` and follow the directions.
+14. Verify the release was created and that the binary <version>.tar.gz file
     is in the assets for the release.
 
-
 (*) Optional, Best Practice: Test the latest database changes on a production database.
 
 1. Change your `.env` so the `$DB_NAME` variable is the correct one for a production database.
-2. Create your database migration script by running `yarn migrate`.  This will create a file `migration-$DB_NAME.sql`.
-3. Catenate the latest release file into the output `cat server/models/migrations/next/migrate.sql >> migration-$DB_NAME.sql`.
-4. Build the migration script targetting your database. `mysql $DB_NAME < migration-$DB_NAME.sql`
+2. Create your database migration script by running `yarn migrate`.  This will create a release migration file `migration-$DB_NAME.sql`.
+3. Append the current migration file into the release migration file:
+ - `cat server/models/migrations/next/migrate.sql >> migration-$DB_NAME.sql`.
+4. Build the migration script targetting your database.
+ - `mysql $DB_NAME < migration-$DB_NAME.sql`
 5. If no errors occur, remove the file `migration-$DB_NAME.sql` to prevent it from getting checked into SQL.

docs/en/for-developers/end-to-end-tests.md

@@ -2,9 +2,9 @@
 
 BHIMA has a large collection of end-to-end tests using the [Playwright testing environment](https://playwright.dev/docs/intro).  The following guidelines how to get the tests working in your environment.  This description assumes that you have already set up BHIMA development environment (see [Installation](./installing-bhima.md)).
 
-1. Install Playwwright:
+1. Install Playwwright (the tests currently only use the chromium browser):
 ```bash
-  npm install playwright
+  npm install playwright chromium
 ```
 
 2. Verify that everything is consistent.  The following commands should give the same version numbers:
@@ -14,10 +14,6 @@ BHIMA has a large collection of end-to-end tests using the [Playwright testing e
   npx playwright --version
 ```
 
-3. Install browsers that Playwright requires
-```bash
-  npx playwright install
-```
 NOTE:  If you upgrade your version of Playwright in your sandbox, you may need to run this command again to update the browsers for Playwright.
 
 4. Run the end-to-end tests (see `package.json` for the commands for this).

docs/en/for-developers/installing-bhima.md

@@ -29,6 +29,7 @@ sudo apt-get update
 sudo apt-get install git
 
 # Install MySQL with the following command:
+# (On Debian 12, check [Installing MySQL on Debian](https://www.digitalocean.com/community/tutorials/how-to-install-the-latest-mysql-on-debian-10) )
 sudo apt-get install mysql-server
 
 # Run the following commands to install Redis:
@@ -58,10 +59,12 @@ curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
 echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
 sudo apt-get update && sudo apt-get install yarn --no-install-recommends
 
-### Install chromium browser ('chrome' below on Debian)
+# Install chromium browser
+# (On debian, you will also need to install 'chromium-driver' separately)
 sudo apt install chromium-browser
 
 # Install extra needed dependencies
+# (On Debian, check the `Dockerfile` for other dependencies)
 sudo apt-get install libx11-xcb1 libxcomposite1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6
 ```
 
@@ -222,7 +225,13 @@ Our tests are broken into unit tests, end to end tests, and integration tests. T
 2. **Server Unit Tests** - Server libraries are unit tested with mocha and chai, similar to the integration tests. To run them, type
    `yarn test:server-unit.`
 3. **Client Unit Tests** - Client components are unit tested with karma which you should have installed if you installed all dependencies. Karma launches a chrome browser to execute the tests. To run them, type `yarn test:client-unit`.
-4. **End to End Tests** - The entire stack is tested with end to end tests using [playwright](https://playwright.dev/).  You can run these tests with `yarn test:e2e-account`, `yarn test:e2e-stock`, and `yarn test:e2e-?`.
+4. **End to End Tests** - The entire stack is tested with end to end tests using [playwright](https://playwright.dev/).  To enable the end-to-end tests, see [Running end-to-end tests](./end-to-end-tests.md).
+You can run the end-to-end tests with
+- `yarn test:e2e-account`  _or_
+- `yarn test:e2e-all` _or_
+- `yarn test:e2e-?` _(where ? varies from 1 to 8)_.
+
+Note: test:e2e-3 includes test:e2e-account.
 
 You can run all non-end-to-end tests by simply typing `yarn test`.