opensearch-project · BSFishy · Mar 10, 2023 · Mar 10, 2023
@@ -4,15 +4,15 @@ Here are our responses to questions we expect to get frequently.
 
 ## What is the OpenSearch UI Framework?
 
-The OpenSearch UI Framework (OUI) is a design library in use at OpenSearch Project to build React applications that need to share our branding and aesthetics. It distributes UI React components and static assets for use in building web layouts. Alongside the React components is a SASS/CSS layer that can be used independently on its own.
+The OpenSearch UI Framework (OUI) is a design library used by the OpenSearch Project to build React applications that need to share our branding and aesthetics. It distributes UI React components and static assets for use in building web layouts.
 
 ## Can I use OUI?
 
-Yes, but be aware of the [license](LICENSE) as always. Although the roadmap and priorities are directed by our own usage within Elastic, we do attempt to make the platform generically useful for any React application and try to test for it.
+Yes, but be aware of the [license](LICENSE) as always. The roadmap and priorities are directed by usage within the OpenSearch project.
 
 ## What is the versioning, releases and upgrade strategy?
 
-We use [semver](https://semver.org/) for versioning and use that to denote breaking changes in OUI upgrades. Traditionally we consider API changes in our prop names or existing component functionality to be a reason for a breaking change, but do not track the renaming of CSS selectors, mixins or other style changes under this same rigor.
+We use [semver](https://semver.org/) for versioning and use that to denote breaking changes in OUI upgrades. We consider API changes in our prop names or existing component functionality to be a reason for a breaking change, but do not consider renaming of CSS selectors, mixins, or other style changes to be breaking.
 
 Traditionally releases are made weekly against whatever is in master and you can upgrade from NPM as you see fit.
 
@@ -24,12 +24,8 @@ For styling we use Sass and generate a final CSS blob for the entire library, wi
 
 ## Can I contribute to OUI
 
-Yes! We accept PRs regularly similar to our other Elastic repos. You can find documentation around creating and submitting new components in [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## Why is OUI open source?
-
-Many of our products themselves are open source and rely upon this library to function. The OpenSearch UI Framework began as a folder of code in Kibana and we decided it could be used beyond that codebase. It exists as an independent library so that patterns can be shared across teams and design standards can be scaled across our organization. Since most of our products are open source, we treat this one similarly as far as public publishing and conversation even if its usage tends to focus more inward towards Elastic itself.
+Yes! We accept PRs regularly similar to our other OpenSearch repos. You can find documentation around creating and submitting new components in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## What about reporting bugs and feature requests?
 
-Bug reports and feature requests are most welcome, but our roadmap is driven primarily by internal usage.
+Bug reports and feature requests are welcome!
@@ -45,7 +45,7 @@ yarn start --port 9000
 
 OUI expects that you polyfill ES2015 features, e.g. [`babel-polyfill`](https://babeljs.io/docs/usage/polyfill/). Without an ES2015 polyfill your app might throw errors on certain browsers.
 
-OUI also has `moment` and `@elastic/datemath` as dependencies itself. These are already loaded in most Elastic repos, but make sure to install them if you are starting from scratch.
+OUI also has `moment` and `@elastic/datemath` as dependencies itself. These are already loaded in most OpenSearch repos, but make sure to install them if you are starting from scratch.
 
 ## What's available
 

@@ -46,4 +46,4 @@ The **set** of failures for each page will be denoted by a line with the URL of
 
 ## Testing environment
 
-This testing suite runs in a Docker container built and maintained by the OUI team and published to the Elastic Container Registry. Any environment-related failures should be investigated starting with the Docker directory located at [`scripts/docker-puppeteer/`](../scripts/docker-puppeteer/README.md).
+This testing suite runs in a Docker container built and maintained by the OUI team. Any environment-related failures should be investigated starting with the Docker directory located at [`scripts/docker-puppeteer/`](../scripts/docker-puppeteer/README.md).
@@ -4,15 +4,13 @@
 
 OUI expects that you polyfill ES2015 features, e.g. [`babel-polyfill`](https://babeljs.io/docs/usage/polyfill/). Without an ES2015 polyfill your app might throw errors on certain browsers.
 
-OUI also has `moment` and `@elastic/datemath` as dependencies itself. These are already loaded in most Elastic repos, but make sure to install them if you are starting from scratch.
+OUI also has `moment` and `@elastic/datemath` as dependencies itself. These are already loaded in most OpenSearch repos, but make sure to install them if you are starting from scratch.
 
 ## What's available
 
-OUI publishes React UI components, JavaScript helpers called services, and utilities for writing Jest tests. Please refer to the [OpenSearch UI Framework website](https://elastic.github.io/eui) for comprehensive info on what's available.
+OUI publishes React UI components, JavaScript helpers called services, and utilities for writing Jest tests. Please refer to the [OpenSearch UI website](https://oui.opensearch.org) for comprehensive info on what's available.
 
-OUI is published through [NPM](https://www.npmjs.com/package/@opensearch-project/oui) as a dependency. We also provide a starter projects for:
-- [GatsbyJS](https://github.com/elastic/gatsby-oui-starter)
-- [NextJS](https://github.com/elastic/next-oui-starter)
+OUI is published through [NPM](https://www.npmjs.com/package/@opensearch-project/oui) as a dependency.
 
 ### Components
 
@@ -180,11 +178,11 @@ We do not recommend customizing OUI components by applying styles directly to OU
 
 ## Using the `test-env` build
 
-OUI provides a separate babel-transformed and partially mocked commonjs build for testing environments in consuming projects. The output is identical to that of `lib/`, but has transformed async functions and dynamic import statements, and also applies some useful mocks. This build mainly targets Kibana's Jest environment, but may be helpful for testing environments in other projects.
+OUI provides a separate babel-transformed and partially mocked commonjs build for testing environments in consuming projects. The output is identical to that of `lib/`, but has transformed async functions and dynamic import statements, and also applies some useful mocks. This build mainly targets OpenSearch Dashboard's Jest environment, but may be helpful for testing environments in other projects.
 
 ### Mapping to the `test-env` directory
 
-In Kibana's Jest configuration, the `moduleNameMapper` option is used to resolve standard OUI import statements with `test-env` aliases.
+In OpenSearch Dashboard's Jest configuration, the `moduleNameMapper` option is used to resolve standard OUI import statements with `test-env` aliases.
 
 ```js
 moduleNameMapper: {

@@ -27,5 +27,5 @@ This makes your React component available for import into your project.
 
 ### 👉 Refer to the [Documentation Guidelines](documentation-guidelines.md) for more instruction on writing docs.
 
-[docs]: https://oui.opensearch.org/
+[docs]: https://oui.opensearch.org
 [docs-logical-group]: component-development.md#logically-grouped-components
@@ -89,6 +89,6 @@ _\** Run `yarn && yarn start` to view the OUI docs site locally._
 
 
 [icons]: https://oui.opensearch.org/#/display/icons
-[docs]: https://oui.opensearch.org/
+[docs]: https://oui.opensearch.org
 [sketch-SVGO-plugin]: [https://www.sketch.com/extensions/plugins/svgo-compressor/]
 [sketch-symbol-organizer-plugin]: [https://github.com/sonburn/symbol-organizer]
@@ -130,7 +130,7 @@ There are a couple themes to keep in mind when adding snippets:
 
 ## Adding playground toggles
 
-Most documentation pages include a [playground section](https://oui.opensearch.org/#/layout/accordion) where consumers can interact with the component's props to see in real time how different configurations affect visual and functional output. Generally, the playground system will automatically generate the correct toggle type; for instance, a text input for props that accept string values, and a switch input for props that accept boolean values.
+Most documentation pages include a [playground section](https://oui.opensearch.org/#/layout/accordion/playground) where consumers can interact with the component's props to see in real time how different configurations affect visual and functional output. Generally, the playground system will automatically generate the correct toggle type; for instance, a text input for props that accept string values, and a switch input for props that accept boolean values.
 
 ### Toggles for required props
 
@@ -220,4 +220,4 @@ Any updates to the `src/` folder require an entry in the [CHANGELOG.md](../CHANG
 * Avoid documenting internal implementation changes that don't affect the public interface
 * Write your entry in the **past tense**, starting with a verb (e.g. Added... , Fixed...)
 
-[docs]: https://oui.opensearch.org/
+[docs]: https://oui.opensearch.org
@@ -1,5 +1,7 @@
 # Release process
 
+> Note: this is legacy documentation that doesn't apply to current OUI releases
+
 The release process is started by running the following command.
 
 ```shell
@@ -14,61 +16,10 @@ After the version is bumped, the release script automatically updates `CHANGELOG
 
 The command will prompt you for your git credentials. If you are using 2FA for git (which you should be) then your git password must be a [one time token](https://github.com/settings/tokens).
 
-That's it. The latest changes were published to GitHub, a new `git` tag now exists on GitHub, the new release can be installed from `npm`, and the [documentation site][docs] will update momentarily<sup>\*</sup>.
-
-<sup>_\* GitHub Pages sites are cached aggressively and can sometimes take a couple of minutes to update._</sup>
+That's it. The latest changes were published to GitHub, a new `git` tag now exists on GitHub, the new release can be installed from `npm`, and the [documentation site][docs] will update momentarily.
 
 ## `@elastic/eslint-plugin-eui`
 
 For information on releasing the eslint plugin checkout the readme in [packages/eslint-plugin/README.md](../packages/eslint-plugin/README.md)
 
 [docs]: https://oui.opensearch.org/
-
-# Backport process
-
-In general, we strongly encourage updating to the latest version of OUI to obtain bug fixes, and we do not actively consider backporting fixes to previous major or minor release versions. The exception to this is when supporting Kibana's release process, as we want to avoid pushing larger changes near the feature freeze.
-
-### Tracking issue
-
-When preparing for a backport a GitHub issue should be created in OUI referencing the relevant issues and/or PRs to be included - see https://github.com/elastic/eui/issues/3386 as an example. This issue is used to keep track of the patch's completion progress and to ensure the desired changes are included in the release.
-
-### Patch process
-
-This provides a walkthrough of the patching & backport release process; examples are taken from the release of v22.3.1 based on https://github.com/elastic/eui/issues/3386
-
-* Unless it is unreasonable, begin by performing a full release from the `master` branch. This ensures the changelog is prepared for referencing later by the backport, and pulls in all commits that will be used by the backport.
-  * Switch to `master` - `git checkout master`
-  * Run the release script and follow the prompts - `npm run release`
-* Identify the target version of OUI to patch; GitHub issue says the new version should be `22.3.1` and I confirmed the patch's base is `22.3.0`
-  * in the OUI git repo, checkout the release tag the patch is intended for - `git checkout v22.3.0`
-  * create a new branch from the versioned tag, the name is unimportant but I use the target version without a leading `v` - `git checkout -b 22.3.1`
-* Run `yarn` to ensure you have the correct dependencies for that point in time installed
-* Apply the commit(s) with the desired changes
-  * GitHub issue references #3369, #3378, #3330, and #3398
-  * We always use squash merges, so each PR has a single commit hash to include
-    * For each PR, find the merge commit
-    * For example, #3369's merge message is
-      ![3369 merge](https://d.pr/i/l002Vu.png)
-      giving `797057a` as the commit hash
-    * For this release, we have `797057a`, `9ba25c0`, `68080d2`, and `42c7ced`
-    * Cherry pick the commit hashes into the backport branch and resolve any conflicts - `git cherry-pick 797057a 9ba25c0 68080d2 42c7ced`
-      * Resolve changelog conflicts by taking the base version (`22.3.0`'s side in this example) and adding the cherry-picked entry to the `master` heading
-      * You may need to re-run yarn in order to commit changes, if the commit modified dependencies
-      * Remember to continue cherry picking with `git cherry-pick --continue` until all commits have been applied
-* Start the dev server and check that the intended changes have been properly applied, you don't want to repeat this process to patch the patch - `yarn start`
-* Once everything looks correct, it's time to release; the `yarn release` script only works when releasing from `master`, so we'll run [a subset of those steps](https://github.com/elastic/eui/blob/06fc9a6880766168aec1a622873e7f6fe1b3d42b/scripts/release.js#L34-L57) manually
-  * Run the unit tests again - `npm test`
-  * Create the release builds - `npm run build`
-  * Use npm to update package.json & package-lock.json version, git commit, and git tag - `npm version patch`
-  * Push the version commit & tag to upstream - `git push upstream --tags`
-  * Publish the new version to npm
-    * Get your npm One Time Password (OTP) from Google Authenticator, Authy, etc
-    * Publish with your OPT and the new version as the tag - `npm publish --tag=22.3.1 --otp=your-one-time-password`
-* Update `master`'s changelog to include this release
-  * On the branch you used to build & release, copy the relevant changelog section - e.g. contents of `## [`22.3.1`](https://github.com/elastic/eui/tree/v22.3.1)`
-  * Checkout `master` - `git checkout master`
-  * Paste the changelog section at the correct location in _CHANGELOG.md_
-    * Include an extra line at the top of this section describing it as a backport, e.g. **Note: this release is a backport containing changes originally made in `23.0.0`, `23.1.0`, and `23.2.0`**
-  * Commit the changelog entry to master and push - `git commit -anm "changelog" && git push`
-* Let people know the backport is released
-* Celebrate profusely
@@ -1,6 +1,6 @@
 ## How OUI theming works
 
-OUI can be easily themed by overwriting the [global styling](https://github.com/elastic/eui/tree/master/src/global_styling)
+OUI can be easily themed by overwriting the [global styling](https://github.com/opensearch-project/oui/tree/main/src/global_styling)
 variables. Currently we maintain the following themes:
 
 * theme_light (the default OUI theme)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -46,4 +46,4 @@ The set of failures for each page will be denoted by a line with the URL of

		## Testing environment

		This testing suite runs in a Docker container built and maintained by the OUI team and published to the Elastic Container Registry. Any environment-related failures should be investigated starting with the Docker directory located at [`scripts/docker-puppeteer/`](../scripts/docker-puppeteer/README.md).
		This testing suite runs in a Docker container built and maintained by the OUI team. Any environment-related failures should be investigated starting with the Docker directory located at [`scripts/docker-puppeteer/`](../scripts/docker-puppeteer/README.md).