Skip to content

Latest commit

 

History

History
130 lines (88 loc) · 7.2 KB

beta-only-features.md

File metadata and controls

130 lines (88 loc) · 7.2 KB
Raw

Adding features to be released in the beta channel (only)

The primary NPM package released from this repository is @azure/communication-react.

We maintain two "release channels" for this package.

  • Stable releases - follow semantic versioning, e.g. 1.0.0
  • Beta releases - do not follow sematnic versioning. These are packages with a -beta.X suffix, e.g. 1.0.1-beta.3

Our beta releases often carry features that are not yet stabilized. A feature may be restricted to beta channel for one of two reasons.

  • A feature that is actively being developed. Feature will be released in a stable package once it is beta-tested.
  • A feature that depends on a feature from underlying Azure Communication Service features that are in themselves in the beta phase. This feature can only be released in a stable package once the underlying features are released in a stable package.

The key difference from many standard NPM packages is that some features can stay in the beta packages across intervening stable package releases.

Conditional compilation

We follow a green-trunk development practice. This means that all development happens on the main branch, and all releases are generated by creating short-lived branches off of main. The need to carry some features that are released in the beta channel but not in intervening stable package releases means that we need a way to enable / disable these features in the releases. Additionally, we need to be able to switch between beta and stable dependencies for underlying Azure Communication Service libraries.

We achieve this by conditionally compiling away code to drop features from the stable package release.

All build, test, local development server scripts can compile the code in this repository in one of two flavors:

  • beta: This is the default build flavor. It includes all code in the packges, and depends on the beta flavors of some of our dependencies.
  • stable: Conditionally compiled code is removed when building this flavor. It also depends on only the stable flavors of our dependencies.

Tooling

To switch between flavors:

rush switch-flavor:stable
# Need to rebuild from scratch because that command cleans all build caches.
rush build

To switch back to beta flavor:

rush switch-flavor:beta
# Need to rebuild from scratch because that command cleans all build caches.
rush build

All the build tooling is aware of build flavor and works as expected:

rush build
rush test
rush lint
# ... etc.

Similarly, commands you use to work on a packlet locally, continue to work for both flavors:

cd samples/Chat
rushx build
rushx test
rushx start
# ... etc.

This is especially useful because rush build may hide detailed errors upon failure.

The only exception is rush update. There is a separate command to update dependencies for stable flavored build:

rush update:stable

Conditionally adding a feature

You must first define your new feature by adding it to the features list in this config file.

This repository contains a live document that describes how you can then add code that is conditionally compiled, and also walks through common scenarios you might encounter when trying to add a beta-only feature.

Stabilizing a feature

Careful scoping of defined features will allow you to easily stabilize the feature. When you are ready to add your feature to the stable build:

  • One-step stabilization: Include all associated conditionally compiled code in the stable flavored build by moving your feature to stabilizedFeatures in the defined features config file.
    • Switch to stable flavor and build, test and run samples to try out your stabilized feature.
    • You will also get the updated API files for the stable build from this step. You can use this for API review.
  • Clean up: Once your feature is shipped in a stable release, remove all references to conditional compilation directive for your feature, and remove your feature from stabilizedFeatures list.
    • Note: If some code has other conditional compilation directives along with your (now stable) feature, remove all directives (not only yours), so that the code is included in the stable flavor build unconditionally.

This example PR for stabilizing a feature includes the generated API diff for this feature.

This example PR cleans up previously stabilized feature flag.

Developing conditional compilation feature

One of the challenge to develop conditional compilation feature is you will have to imagine what code would be generated after adding your comments, and run preprocess comment, compile them and compare two files side by side. To solve this problem, we introduce a vscode extension named Before After Diff Checker, which is a small tool to do all the preprocess automation and compare files side by side for you.

To install the extension:

  1. Press Ctrl + Shift + P when you have your VSCode open, type Extensions: Show Recommended Extensions, press Enter, or you can directly search for Before After Diff Checker in Extension search bar
  2. You will see Before After Diff Checker on the left side panel, install it
  3. Restart your VSCode to activate the extension

To use the extension:

  1. Switch stable flavor using rush switch-flavor:stable
  2. Press Ctrl + Shift + P when you have your VSCode open, type Before-after Diff: Enable On Save Feature, press Enter
  3. Start editing your code, once you save the file, the extension will run the preprocess command and beautify the generated file
  4. Once finished, a side by side diff window will be opened, left side will be generated code, and right side will be original code
  5. You can start edit original file from right side, and you will see left side file changes within seconds after you save it.
  6. Don't forget to disable it by Ctrl + Shift + P -> Before-after Diff: Disable On Save Feature when you finish developing conditional compilation code.

The extension is just a small tool to run a specific command to generate code and compare them based on relative path, you can easily check and edit settings for the extension: .vscode/settings.json

Releases

Conditional compilation necessitates a few extra steps when we release a package:

  • Remove beta-only code: This is taken care of by the same tooling that we use rush switch-flavor:stable && rush build
  • Change dependencies to be the beta vs stable versions

Both of these steps are implemented in the GitHub actions that create a release branch.

You an help with the manual step of figuring out what the CHANGELOG is in each release. When running rush changelog, use the change type

  • prerelease for a change that affects only the beta flavor build
  • patch, minor or major for changes that affect the stable (and of course beta) flavor build as appropriate.
  • none for documentation changes etc that don't affect the NPM bundle meaningfully.