From 46ce4739a61a0b0c099868bb6e582cef454ff206 Mon Sep 17 00:00:00 2001
From: TWIINE <122885804+Twiineenock@users.noreply.github.com>
Date: Thu, 21 Nov 2024 13:55:39 +0300
Subject: [PATCH] (feat) O3-3525: Enhance README.md Documentation for
 openmrs-esm-home (#211)

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 66 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 8fba07ab9..ef514bfed 100644
--- a/README.md
+++ b/README.md
@@ -4,19 +4,78 @@
 
 # OpenMRS ESM Home
 
-An [OpenMRS Microfrontend](https://openmrs.atlassian.net/wiki/spaces/projects/pages/26936899/OpenMRS+3.0+A+Frontend+Framework+that+enables+collaboration+and+better+User+Experience) for frontend modules tied to the home page.
+An [OpenMRS Microfrontend](https://openmrs.atlassian.net/wiki/spaces/projects/pages/26936899/OpenMRS+3.0+A+Frontend+Framework+that+enables+collaboration+and+better+User+Experience) for the O3 Home page.
 
 ## What is this?
 
-openmrs-esm-home is an in-browser 
-[javascript module](https://github.com/openmrs/openmrs-rfc-frontend/blob/master/text/0002-modules.md) 
-that is a [single-spa application](https://single-spa.js.org/docs/building-applications.html).
-It is responsible for rendering the UI for the landing page after the user logs in.
+openmrs-esm-home is an in-browser [javascript module](https://github.com/openmrs/openmrs-rfc-frontend/blob/master/text/0002-modules.md) 
+that is a [single-spa application](https://single-spa.js.org/docs/building-applications.html). It is responsible for rendering the UI for the landing page after the user logs in.
 
 ## Contributing / Development
 
-[Setup local development environment for OpenMRS SPA](https://o3-docs.openmrs.org/docs/frontend-modules/development)
+Check out the developer documentation [here](https://o3-docs.openmrs.org/docs/frontend-modules/development).
+
+This monorepo uses [yarn](https://yarnpkg.com/).
+
+To install the dependencies, run:
+
+```bash
+yarn
+```
+
+To start a dev server for the home app, run:
+
+```bash
+yarn start --sources 'packages/esm-home-app'
+```
+
+## Running tests
+
+To run all tests, run:
+
+```bash
+yarn turbo run test --filter=@openmrs/esm-home-app
+```
+
+To run a specific test file, run:
+
+```bash
+yarn turbo run test -- <test-file-name>
+```
+
+The above command will only run tests in the file or files that match the provided string.
+
+To generate a `coverage` report, run:
+
+```bash
+yarn turbo run coverage
+```
+
+By default, `turbo` will cache test runs. This means that re-running tests without changing any of the related files will return the cached logs from the last run. To bypass the cache, run tests with the `force` flag, as follows:
+
+```bash
+yarn turbo run test --force
+```
+
+## Troubleshooting
+
+If you notice that your local version of the application is not working or that there's a mismatch between what you see locally versus what's in [dev3](https://dev3.openmrs.org/openmrs/spa), you likely have outdated versions of core libraries. To update core libraries, run the following commands:
+
+```bash
+# Upgrade core libraries
+yarn up openmrs@next @openmrs/esm-framework@next
+
+# Reset version specifiers to `next`. Don't commit actual version numbers.
+git checkout package.json
+
+# Run `yarn` to recreate the lockfile
+yarn
+```
 
 ## Design Patterns
 
-Please visit our [design system](https://om.rs/o3ui) documentation website for documentation about our design patterns.
+For documentation about our design patterns, please visit our [design system](https://om.rs/o3ui) documentation website.
+
+## Configuration
+
+Please see the [Implementer Documentation](https://wiki.openmrs.org/pages/viewpage.action?pageId=224527013) for information about configuring modules.