# Widgetbook Cloud Review

Widgetbook Cloud introduces a _Review_ feature, that empowers Flutter teams to compare changes in the user interface. Drawing inspiration from Pull Request reviews, this feature allows a streamlined analysis of UI changes.

## Overview

1. [Understanding Reviews](/widgetbook-cloud/reviews#understanding-reviews)
2. [Review Statuses](/widgetbook-cloud/reviews#review-statuses)
3. [Requirements](/widgetbook-cloud/reviews#requirements)
4. [Set up addons and knobs](/widgetbook-cloud/reviews#how-to-set-up-addons-and-knobs)
5. [Add a Figma design link](/widgetbook-cloud/reviews#how-to-add-a-figma-design-link)
6. [Publishing a review](/widgetbook-cloud/reviews#publishing-a-review)

---

## Understanding Reviews

A Widgetbook Review lets teams contrast UI changes between two versions. Moreover, it enables comparison of the current Widget version against its Figma design.
- In a standard Pull Request, code differences between a `base` (previous version) and a `feature` (new version) branch are evaluated.
- Similarly, in a Widgetbook Review, visual differences between the base build (last version) and feature build (current version) are assessed.
For every pull request in your Git provider, our integration initiates a Widgetbook Cloud review. To facilitate this visual comparison, Widgetbook Cloud necessitates uploaded builds for both base and feature branches.

## Review Statuses

Different statuses can be assigned to the reviews:

- **Open:** Awaiting assessment.
- **Merged:** Linked with merged PRs, thus considered merged.
- **Closed:** Associated with closed PRs, hence viewed as closed.
- **Updating:** Missing crucial information for an open classification. A review qualifies as open if:
  - A head build is accessible, AND
  - A base build is available or at least one use-case is tied with a DesignLink.

Once a review's changes are approved, the developer closes the Pull-Request, updating the review status to `merged`.

## Requirements

To harness the Widgetbook Cloud _Review_ feature, ensure your setup aligns with the following prerequisites:

- Incorporate the [widgetbook_generator package](https://pub.dev/packages/widgetbook_generator) version `{{ versions.generator }}`. No additional configuration needed.
- Integrate the [widgetbook package](https://pub.dev/packages/widgetbook) version `{{ versions.widgetbook }}`. No extra setup required.
- Employ the CLI from [widgetbook_cli package](https://pub.dev/packages/widgetbook_cli).
- Set up our GitHub app.

## How to set up addons and knobs

In order for the addons and knobs in your Widgetbook builds to work with our review feature, make sure you have the `WidgetbookCloudIntegration` added to the `integrations` array in your `Widgetbook` app:

```dart
@widgetbook.App()
class WidgetbookApp extends StatelessWidget {
  const WidgetbookApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Widgetbook.material(
      // Use the generated directories variable
      directories: directories,
      addons: [],
      integrations: [
        // Important to send addons & knobs to Widgetbook Cloud
        WidgetbookCloudIntegration(),
      ],
    );
  }
}
```

## How to add a Figma design link

To add a Figma design link, you need to provide the `designLink` property to a use case:
1. Got to Figma
1. Go to the component that resembles your Widget
1. Right-mouse click on the component
1. Select `Copy/Paste as` > `Copy Link`
1. Set the `designLink` property of the `@UseCase` annotation by pasting the copied link
1. Let the re-run `build_runner` 
1. Commit the changes to Git

```dart
// Example from https://github.com/widgetbook/groceries-demo/blob/chore/design-link-for-appbar/lib/core/app_bar.dart
@UseCase(
  designLink: 'https://www.figma.com/file/EXuEpwiyksLAejYX1qr1v4/Fluttercon-Berlin-2023-Demo?type=design&node-id=277-3056&mode=design&t=nVL8hLmc1jlcilZL-4',
  name: 'Default',
  type: AppBar
)
```

## Publishing a Review

The review feature works best if a build for the base branch and a build for the feature branch is available. 
In addition to uploading a feature branch, information about what has changed is important. 
To add this information, you can use the `--base-branch` argument of the CLI: `widgetbook publish --api-key KEY --base-branch BASE-BRANCH`.

<Info>
    Most CI/CD providers expose the `BASE-BRANCH` via environment variables for pull-requests. Check our [CI/CD Setup guide](/widgetbook-cloud/setup) for more insights.
</Info>

### Example

```bash
# Install dependencies
flutter pub get
# !!! 
# !!! Run the build runner
# !!! This is mandatory even if you have committed the generated files since 
# !!! the generator creates files that are consumed by the Widgetbook CLI
# !!!
flutter pub run build_runner build --delete-conflicting-outputs
# Build the Widgetbook
flutter build web -t lib/ui_catalogs.widgetbook.dart
# Install the CLI
dart pub global activate widgetbook_cli
# Run the CLI
widgetbook publish --api-key API-KEY --base-branch main
```

## Review Information
To populate a review, information regarding the changes in use cases is mandatory. When the `--base-branch` argument is used, the CLI fetches details about the altered use cases.

<Info>
Widgetbook Cloud showcases Reviews for all pull requests. But, only those Reviews with use case alterations are accessible.
</Info>
<Warning>
At present, Widgetbook Cloud exclusively displays use cases that underwent changes, additions, or removals within the feature branch compared to the base branch. Consequently, existing use cases, even if unreviewed, won't be displayed.
</Warning>