Angular Public API and Goldens

Angular, one of the most popular web application frameworks, uses a sophisticated system to manage its public API surface.

This system, centered around the concept of "Goldens" helps maintainers and contributors track changes to the public API, ensuring transparency and facilitating easier review processes. Let's dive deep into how this works and how you can contribute effectively to the Angular repository.

Understanding Public API in Angular

In Angular, the public API refers to the set of features, functions, and interfaces that are officially supported and intended for use by developers building applications with the framework. These APIs are typically marked with a @publicApi decorator in the source code.

The Goldens Folder

The Goldens folder is a crucial part of Angular's API management system. Here's what you need to know:

1. Location: The Goldens folder is found in the root of the Angular repository.

2. Purpose: It contains Markdown files that document the current public API surface for each Angular package.

3. Structure: Each package in Angular (e.g., core, animations, router) has its own Markdown file in the Goldens folder.

For example, the structure might look like this:

Contributing to Angular: Updating the Public API

When you're contributing to Angular and your changes affect the public API, you need to update the corresponding Golden file. Here's the process:

1. Make your changes to the source code.

2. If you're adding or modifying a public API, ensure it's properly documented with JSDoc comments and the @publicApi decorator.

3. Update the Golden file for the package you modified.

Updating a Specific Package's Golden

To update the Golden for a specific package (e.g., animations), use the following Bazel command:

yarn bazel run //packages/animations:animations_api.accept

This command will update the animations.md file in the Goldens folder to reflect your changes.

Updating All Goldens

If you've made changes that might affect multiple packages, you can update all Goldens at once:

yarn public-api:update

This command will scan all packages for public API changes and update the corresponding Golden files as needed.

Example: Adding a New Public API

Let's walk through an example of adding a new public API to the animations package:

Add your new function to the animations package:

// In packages/animations/src/animate.ts for example

/**
 * Creates a new animation with enhanced easing options.
 * @param timing The duration of the animation in milliseconds.
 * @param easing The easing function to use (e.g., 'ease-in', 'ease-out').
 * @publicApi
 */
export function createEnhancedAnimation(timing: number, easing: string): Animation {
  // Implementation details...
}

Run the command to update the animations Golden:

yarn bazel run //packages/animations:animations_api.accept

Check the updated goldens/animations.md file. You should see your new function added:

```ts
//...
// @public
function createEnhancedAnimation(timing: number, easing: string): Animation

Creates a new animation with enhanced easing options.

• timing: The duration of the animation in milliseconds.

• easing: The easing function to use (e.g., 'ease-in', 'ease-out').

Commit these changes and include them in your pull request.

The Role of Bazel

Angular uses Bazel as its build system, which provides several benefits:

1. Caching: Bazel caches build artifacts, speeding up subsequent builds.

2. Selective testing: You can run tests only for the parts of the codebase you've changed.

3. Reproducibility: Builds are more consistent across different environments.

When using Bazel commands, remember to use double slashes (`//`) to separate package paths:

yarn bazel run //packages/core:core_api.accept

Best Practices for Contributors

1. Always check if your changes affect the public API.

2. Run the appropriate commands to update Goldens before submitting your pull request.

3. Include both the source code changes and the updated Golden files in your PR.

4. Be prepared to discuss and justify any changes to the public API during the review process.

By following these practices and understanding the role of the Goldens folder, you'll be well-equipped to contribute effectively to the Angular repository, ensuring that all changes to the public API are properly documented and reviewed.

Thank you Matthieu Riegler and Younes Jaaidi for this awesome time I spent on the video.

Thanks for reading so far 🙏

I’d like to have your feedback so please leave a comment, clap or follow. 👏

Spread the Angular love! 💜

If you really liked it, share it among your community, tech bros and whoever you want! 🚀👥

Don't forget to follow me and stay updated: 📱

• 🔗 LinkedIn

• 📝 Medium

• 🎥 YouTube

• 🐦 Twitter

Thanks for being part of this Angular journey! 👋😁