angular/contributing-docs/google-markers.md

Angular Google Sync Comment Markers Guide

This document describes the comment-based markers used in the Angular repository to manage the synchronization process between the public GitHub repository and Google's internal codebase (google3).

As an Angular contributor, you will occasionally encounter these markers in the codebase. Most external contributors will never need to write these markers themselves. Instead, this guide exists to explain what these markers mean and why they are in the code when you run into them.

These tags are necessary because Google's internal codebase builds and integrates Angular in a slightly different configuration than the public NPM packages. For example, Google may require certain APIs to remain public internally for integration purposes, or might need to bypass public-only configurations. These markers allow the automated sync tooling to adjust the code seamlessly during the import process.

---

Reference Table

The following markers are processed during the synchronization to Google's internal codebase:

Marker	Type	Action in Google's Codebase	Intended Use Case
// 3p-only	Single-line	Strip: Deletes the entire line	Remove imports or calls that only exist in the public version.
// 3p-only-start / // 3p-only-end	Block	Strip: Deletes the entire block	Remove larger chunks of public-only code (e.g., benchmarking suites, public-only adapters).
// g3-only	Single-line	Insert: Uncomments the rest of the line	Export Google-internal symbols or activate Google-specific configurations.
// g3-only-start / // g3-only-end	Block	Insert: Uncomments every line inside	Add larger Google-specific functions or class definitions.

---

Detailed Marker Explanations & Examples

1. Removing Single Lines (// 3p-only)

This tag is appended at the end of a line comment to completely remove that line when the code is synced internally to Google.

• GitHub Source:

  import {ExternalBenchmarkRunner} from './benchmarks'; // 3p-only
  

• Google's Internal Codebase: (The line is completely removed)

---

2. Removing Blocks of Code (// 3p-only-start / // 3p-only-end)

Blocks of code that should only run in the public version are surrounded by these markers. The entire block is stripped during the sync.

• GitHub Source:

  // 3p-only-start
  export function initializeDevTools() {
    console.log('Setting up external devtools...');
    setupExternalDebugger();
  }
  // 3p-only-end
  

• Google's Internal Codebase: (The entire block, including markers, is completely removed)

---

3. Activating Single Lines (// g3-only)

Google-specific code is written as a comment and prefixed with // g3-only. The sync tooling uncomments this line when importing it into Google's codebase.

• GitHub Source:

  // g3-only export {ForeignComponent} from './interface/foreign_component';
  

• Google's Internal Codebase:

  export {ForeignComponent} from './interface/foreign_component';
  

---

4. Activating Blocks of Code (// g3-only-start / // g3-only-end)

Larger blocks of Google-specific code are commented out line-by-line and wrapped in the g3-only start/end markers. The sync tooling strips the markers and uncomments all lines in between.

• GitHub Source:

  // g3-only-start
  // export function getGoogleSpecificConfig() {
  //   return {
  //     enableInternalLogging: true,
  //     useInternalDatabase: true,
  //   };
  // }
  // g3-only-end
  

• Google's Internal Codebase:

  export function getGoogleSpecificConfig() {
    return {
      enableInternalLogging: true,
      useInternalDatabase: true,
    };
  }