From 98dbe9f60ca14697bf0f9f3a63bed2245e9be593 Mon Sep 17 00:00:00 2001 From: Dennis Kigen Date: Fri, 1 Dec 2023 12:16:44 +0300 Subject: [PATCH] (docs) Update release instructions in README --- README.md | 52 ++++++++++++++++++++++------------------------------ 1 file changed, 22 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 40f6977ed..5eb11759d 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,11 @@ :wave: New to our project? Be sure to review the [OpenMRS 3 Frontend Developer Documentation](https://o3-docs.openmrs.org/). You may find the [Introduction](https://o3-docs.openmrs.org/docs/introduction) especially helpful. - Also see the [API documentation](./packages/framework/esm-framework/docs/API.md) for `@openmrs/esm-framework`, which is contained in this repository. - ![OpenMRS CI](https://github.com/openmrs/openmrs-esm-core/workflows/OpenMRS%20CI/badge.svg) ![Check documentation](https://github.com/openmrs/openmrs-esm-core/actions/workflows/docs.yml/badge.svg) - Below is the documentation for this repository. # OpenMRS Frontend Core @@ -152,13 +149,10 @@ yarn turbo test --force ### Linking the framework -If you want to try out changes to a framework library, you will -probably want to `yarn link` or `npm link` it into a frontend module. -Note that even though frontend modules import from `@openmrs/esm-framework`, -the package you need to link is the sub-library; for example, if you are trying -to test changes in `packages/framework/esm-api`, you will need to link it: +If you want to try out changes to a framework library, you will probably want to `yarn link` or `npm link` it into a frontend module. +Note that even though frontend modules import from `@openmrs/esm-framework`, the package you need to link is the sub-library; for example, if you are trying to test changes in `packages/framework/esm-api`, you will need to link it: -``` +```sh yarn link path/to/openmrs-esm-core/packages/framework/esm-framework yarn link path/to/openmrs-esm-core/packages/framework/esm-api ``` @@ -166,7 +160,8 @@ yarn link path/to/openmrs-esm-core/packages/framework/esm-api This satisfies the build tooling, but we must do one more step to get the frontend to load these dependencies at runtime (see docs on [Runtime Dependencies](https://o3-dev.docs.openmrs.org/#/main/deps)). -Here, there are two options. + +Here, there are two options: #### Method 1: Using the frontend dev server @@ -185,40 +180,37 @@ If you're not able to get this working, try the Read the [dev documentation](https://o3-dev.docs.openmrs.org/#/getting_started/setup?id=import-map-overrides) about import map overrides if you have not already. -In `esm-core`, start the app shell with `yarn run:shell`. Then, in the patient chart -repository, `cd` into whatever packages you are working on and run `yarn serve` -from there. Then use the import map override tool in the browser to tell the frontend -to load your local patient chart packages. +In `esm-core`, start the app shell with `yarn run:shell`. Then, in the patient chart repository, `cd` into whatever packages you are working on and run `yarn serve` from there. Then use the import map override tool in the browser to tell the frontend to load your local patient chart packages. #### Once it's working -Please note that this will result in entries being added to the package.json file -in the `resolutions` field. These changes must be undone before creating your PR, -which you can do by running `yarn unlink --all` in the patient chart repo. +Please note that this will result in entries being added to the package.json file in the `resolutions` field. These changes must be undone before creating your PR, which you can do by running `yarn unlink --all` in the patient chart repo. -Check your work by adding a `console.log` at the top level of a file you're -working on in `esm-api`. +Check your work by adding a `console.log` at the top level of a file you're working on in `esm-api`. ### Version and release +We use Yarn [workspaces](https://yarnpkg.com/features/workspaces) to handle versioning in this monorepo. + To increment the version, run the following command: ```sh -yarn release +yarn release [version] ``` -You will need to pick the next version number. We use minor changes (e.g. `3.2.0` → `3.3.0`) -to indicate big new features and breaking changes, and patch changes (e.g. `3.2.0` → `3.2.1`) -otherwise. +Where version corresponds to: + +- `patch` for bug fixes e.g. `3.2.0` → `3.2.1` +- `minor` for new features that are backwards-compatible e.g `3.2.0` → `3.3.0` +- `major` for breaking changes e.g. `3.2.0` → `4.0.0` + +Note that this command will not create a new tag, nor publish the packages. After running it, make a PR or merge to `main` with the resulting changeset. Note that the release commit message must resemble `(chore) Release vx.x.x` where `x.x.x` is the new version number prefixed with `v`. + +This is because we don't want to trigger a pre-release build when effecting a version bump. -Note that this command will not create a new tag, nor publish the packages. -After running it, make a PR or merge to `main` with the resulting changeset. +Once the version bump commit is merged, go to GitHub and [draft a new release](https://github.com/openmrs/openmrs-esm-core/releases/new). -Once the version bump is merged, go to GitHub and -[draft a new release](https://github.com/openmrs/openmrs-esm-core/releases/new). -The tag should be prefixed with `v` (e.g., `v3.2.1`), while the release title -should just be the version number (e.g., `3.2.1`). The creation of the GitHub release -will cause GitHub Actions to publish the packages, completing the release process. +The tag should be prefixed with `v` (e.g., `v3.2.1`), while the release title should just be the version number (e.g., `3.2.1`). The creation of the GitHub release will cause GitHub Actions to publish the packages, completing the release process. > Don't run `npm publish`, `yarn publish`, or `lerna publish`. Use the above process.