@brightspot/ui 1.0.0-alpha.4 → 1.0.1-0

package/README.md

@@ -1,3 +1,5 @@
+Brightspot UI
+=======
 <a id="readme-top"></a>
 <div>
 <h2 align="center">brightspot-ui</h2>
@@ -142,17 +144,87 @@ We use [Storybook](https://storybook.js.org/) for interactive previewing of our
 
 ## Development
 
-* To build, run `yarn build` from the package root to create the `dist` folder
-* To use this package locally, run `yarn pack` to create a distribution package. Then install the node module in your project using `yarn add {/PATH/TO/TARBALL}/brightspot-ui-v{VERSION}.tgz`. __Note:__ You could also use `yarn link` for this or [local paths](https://classic.yarnpkg.com/lang/en/docs/cli/add/).
-* To publish a release, run `npm publish` and follow the prompts. **Make sure to update the version number in the package.json first!**
+### Building the Package
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
+To build the package, run `yarn build` from the package root to create the `dist` folder containing all the compiled assets.
 
-## Frequently Asked Questions
+### Local Development with yarn link
+
+For local development and testing, use `yarn link` to create a symlink between this package and your consuming project. This approach provides real-time updates as you make changes to the brightspot-ui source code.
+
+#### Setting up the link
+
+1. **In the brightspot-ui package directory:**
+   ```sh
+   yarn link
+   ```
+   This registers the package globally on your system for linking.
+
+2. **In your consuming project directory:**
+   ```sh
+   yarn link @brightspot/ui
+   ```
+   This creates a symlink from your project's node_modules to the brightspot-ui package.
+
+#### Working with the linked package
+
+- Any changes you make to the brightspot-ui source code will be immediately available in your consuming project
+- Run `yarn build` in the brightspot-ui directory whenever you make changes to ensure the `dist` folder is updated
+- Your project will use the local development version instead of the published npm version
+
+#### Removing the link
+
+When you're done with local development:
+
+1. **In your consuming project:**
+   ```sh
+   yarn unlink @brightspot/ui
+   yarn install --force
+   ```
+
+2. **In the brightspot-ui package directory:**
+   ```sh
+   yarn unlink
+   ```
+
+This restores your project to use the published version from npm.
 
-Q: How do I know that I set it up correctly?
+### Publishing
 
-A: TODO
+#### Prerelease (Testing)
+
+For testing changes before a full release, create a prerelease version:
+
+```sh
+yarn version --prerelease
+npm publish --tag beta
+```
+
+This automatically increments the version with a prerelease identifier (e.g., `1.2.3-0`) and publishes it under the `beta` tag. Users can install prereleases with:
+
+```sh
+yarn add @brightspot/ui@beta
+```
+
+#### Full Release
+
+For a production release:
+
+```sh
+yarn version --patch  # for bug fixes
+# or
+yarn version --minor  # for new features
+# or
+yarn version --major  # for breaking changes
+
+npm publish
+```
+
+The `yarn version` command automatically updates the version number in package.json and creates a git commit and tag. Choose the appropriate version bump based on the type of changes you're releasing.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Frequently Asked Questions
 
 Q: How can I see examples of the components and theme?
 
@@ -162,4 +234,4 @@ Q: Can I choose which Brightspot UI plugins my project uses?
 
 A: You have full control over which plugins you include in the tailwind.config file. See the ["using plugins"](#using-plugins) section above.
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
+<p align="right">(<a href="#readme-top">back to top</a>)</p>