diff --git a/contributing-docs/google-markers.md b/contributing-docs/google-markers.md new file mode 100644 index 000000000000..787f8fb102f4 --- /dev/null +++ b/contributing-docs/google-markers.md @@ -0,0 +1,95 @@ +# 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**: + ```typescript + 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**: + ```typescript + // 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**: + ```typescript + // g3-only export {ForeignComponent} from './interface/foreign_component'; + ``` +- **Google's Internal Codebase**: + ```typescript + 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**: + ```typescript + // g3-only-start + // export function getGoogleSpecificConfig() { + // return { + // enableInternalLogging: true, + // useInternalDatabase: true, + // }; + // } + // g3-only-end + ``` +- **Google's Internal Codebase**: + ```typescript + export function getGoogleSpecificConfig() { + return { + enableInternalLogging: true, + useInternalDatabase: true, + }; + } + ``` diff --git a/packages/compiler-cli/index.ts b/packages/compiler-cli/index.ts index f8a336d49870..930a08b999cf 100644 --- a/packages/compiler-cli/index.ts +++ b/packages/compiler-cli/index.ts @@ -18,6 +18,7 @@ export * from './src/perform_compile'; // TODO(tbosch): remove this once usages in G3 are changed to `CompilerOptions` export {CompilerOptions as AngularCompilerOptions} from './src/transformers/api'; +// 3p-only-start // Internal exports needed for packages relying on the compiler-cli. // TODO: Remove this when the CLI has switched to the private entry-point. export * from './private/tooling'; @@ -27,6 +28,7 @@ export * from './private/hybrid_analysis'; // Exposed as they are needed for relying on the `linker`. export * from './src/ngtsc/logging'; export * from './src/ngtsc/file_system'; +// 3p-only-end // Exports for dealing with the `ngtsc` program. export {NgTscPlugin, PluginCompilerHost} from './src/ngtsc/tsc_plugin'; diff --git a/packages/compiler-cli/src/ngtsc/core/src/feature_detection.ts b/packages/compiler-cli/src/ngtsc/core/src/feature_detection.ts index 13e9f3319bc7..ae08e06a3f04 100644 --- a/packages/compiler-cli/src/ngtsc/core/src/feature_detection.ts +++ b/packages/compiler-cli/src/ngtsc/core/src/feature_detection.ts @@ -8,7 +8,7 @@ // Note: semver isn't available internally so this import will be commented out. // When adding more dependencies here, the caretaker may have to update a patch internally. -import semver from 'semver'; +import semver from 'semver'; // 3p-only /** * Whether a version of `@angular/core` supports a specific feature. @@ -23,5 +23,6 @@ export function coreVersionSupportsFeature(coreVersion: string, minVersion: stri return true; } - return semver.satisfies(coreVersion, minVersion, {includePrerelease: true}); + // g3-only return true; + return semver.satisfies(coreVersion, minVersion, {includePrerelease: true}); // 3p-only } diff --git a/packages/compiler/src/legacy_optional_chaining_default.ts b/packages/compiler/src/legacy_optional_chaining_default.ts index 11ce3c1e8aa1..f5109882bdbd 100644 --- a/packages/compiler/src/legacy_optional_chaining_default.ts +++ b/packages/compiler/src/legacy_optional_chaining_default.ts @@ -11,4 +11,5 @@ * * This is extracted in order to be patched in G3. */ -export const LEGACY_OPTIONAL_CHAINING_DEFAULT = false; +// g3-only export const LEGACY_OPTIONAL_CHAINING_DEFAULT = true; +export const LEGACY_OPTIONAL_CHAINING_DEFAULT = false; // 3p-only diff --git a/packages/core/primitives/dom-navigation/testing/fake_navigation.ts b/packages/core/primitives/dom-navigation/testing/fake_navigation.ts index 66d15e87b09a..a556713ea49a 100644 --- a/packages/core/primitives/dom-navigation/testing/fake_navigation.ts +++ b/packages/core/primitives/dom-navigation/testing/fake_navigation.ts @@ -6,6 +6,7 @@ * found in the LICENSE file at https://angular.dev/license */ +// 3p-only-start import { NavigationNavigateOptions, NavigationTypeString, @@ -21,6 +22,7 @@ import { NavigationDestination, Navigation, } from '../src/navigation_types'; +// 3p-only-end /** * Fake implementation of user agent history and navigation behavior. This is a @@ -616,13 +618,13 @@ export class FakeNavigation implements Navigation { set oncurrententrychange( _handler: // tslint:disable-next-line:no-any - ((this: Navigation, ev: NavigationCurrentEntryChangeEvent) => any) | null, + ((this: Navigation, ev: NavigationCurrentEntryChangeEvent) => any) | null, ) { throw new Error('unimplemented'); } get oncurrententrychange(): // tslint:disable-next-line:no-any - ((this: Navigation, ev: NavigationCurrentEntryChangeEvent) => any) | null { + ((this: Navigation, ev: NavigationCurrentEntryChangeEvent) => any) | null { throw new Error('unimplemented'); } diff --git a/packages/core/primitives/event-dispatch/src/event_contract_defines.ts b/packages/core/primitives/event-dispatch/src/event_contract_defines.ts index 0a445ca6cd68..85a281ad4d54 100644 --- a/packages/core/primitives/event-dispatch/src/event_contract_defines.ts +++ b/packages/core/primitives/event-dispatch/src/event_contract_defines.ts @@ -10,4 +10,5 @@ * @define Support for the non-bubbling mouseenter and mouseleave events. This * flag can be overridden in a build rule. */ -export const MOUSE_SPECIAL_SUPPORT = false; +// g3-only export const MOUSE_SPECIAL_SUPPORT = goog.define('jsaction.EventContract.MOUSE_SPECIAL_SUPPORT', false,); +export const MOUSE_SPECIAL_SUPPORT = false; // 3p-only diff --git a/packages/core/primitives/event-dispatch/src/event_dispatcher.ts b/packages/core/primitives/event-dispatch/src/event_dispatcher.ts index a549e3d8b925..5ecb529bb1e2 100644 --- a/packages/core/primitives/event-dispatch/src/event_dispatcher.ts +++ b/packages/core/primitives/event-dispatch/src/event_dispatcher.ts @@ -14,7 +14,7 @@ import {UnrenamedEventContract} from './eventcontract'; import {Restriction} from './restriction'; // Necessary to make the `ngDevMode` global types available. -import '../../../src/util/ng_dev_mode'; +import '../../../src/util/ng_dev_mode'; // 3p-only /** * A replayer is a function that is called when there are queued events, from the `EventContract`. diff --git a/packages/core/src/change_detection/constants.ts b/packages/core/src/change_detection/constants.ts index 03299372140b..8e8472f82f23 100644 --- a/packages/core/src/change_detection/constants.ts +++ b/packages/core/src/change_detection/constants.ts @@ -38,6 +38,8 @@ export enum ChangeDetectionStrategy { * explicitly deactivated. * @deprecated Use `Eager` instead. */ + // 3p-only-start // tslint:disable-next-line:no-duplicate-enum-values Default = 1, + // 3p-only-end } diff --git a/packages/core/src/core.ts b/packages/core/src/core.ts index 054cac34be1d..1e89141c41cb 100644 --- a/packages/core/src/core.ts +++ b/packages/core/src/core.ts @@ -76,6 +76,7 @@ export { TRANSLATIONS, TRANSLATIONS_FORMAT, } from './i18n/tokens'; +// g3-only export {ForeignComponent} from './interface/foreign_component'; export {AbstractType, Type} from './interface/type'; export * from './linker'; export * from './linker/ng_module_factory_loader_impl'; @@ -111,6 +112,7 @@ export { outputBinding, twoWayBinding, } from './render3/dynamic_bindings'; +// g3-only export {foreignImport} from './render3/foreign_import'; export {createEnvironmentInjector, createNgModule} from './render3/ng_module_ref'; export {publishExternalGlobalUtil as ɵpublishExternalGlobalUtil} from './render3/util/global_utils'; export * from './resource'; diff --git a/packages/core/src/i18n/tokens.ts b/packages/core/src/i18n/tokens.ts index aa5e1c23640f..cace4d6ed2f1 100644 --- a/packages/core/src/i18n/tokens.ts +++ b/packages/core/src/i18n/tokens.ts @@ -6,7 +6,7 @@ * found in the LICENSE file at https://angular.dev/license */ -/// +/// // 3p-only import {InjectionToken} from '../di/injection_token'; import {inject} from '../di/injector_compatibility'; diff --git a/packages/core/src/metadata/directives.ts b/packages/core/src/metadata/directives.ts index dea9012cdddb..11c923115a82 100644 --- a/packages/core/src/metadata/directives.ts +++ b/packages/core/src/metadata/directives.ts @@ -646,7 +646,7 @@ export interface Component extends Directive { * The foreignImports property specifies components from other frameworks that can be used * within this component's template. * - * @internal + * @internal // 3p-only */ foreignImports?: ForeignComponent[]; @@ -657,7 +657,7 @@ export interface Component extends Directive { * which bring symbols used in the `deferredImports` don't contain other symbols. * * Note: this is an internal-only field, use regular `@Component.imports` field instead. - * @internal + * @internal // 3p-only */ deferredImports?: (Type | ReadonlyArray)[]; diff --git a/packages/core/src/render3/jit/directive.ts b/packages/core/src/render3/jit/directive.ts index a7f741a9ef60..a848a98bdf12 100644 --- a/packages/core/src/render3/jit/directive.ts +++ b/packages/core/src/render3/jit/directive.ts @@ -376,7 +376,8 @@ export function directiveMetadata(type: Type, metadata: Directive): R3Direc return { name: type.name, - legacyOptionalChaining: false, + // g3-only legacyOptionalChaining: true, + legacyOptionalChaining: false, // 3p-only type: type, selector: metadata.selector !== undefined ? metadata.selector : null, host: metadata.host || EMPTY_OBJ, diff --git a/packages/core/src/render3/util/global_utils.ts b/packages/core/src/render3/util/global_utils.ts index 15173c8d8c36..c4e223e7c353 100644 --- a/packages/core/src/render3/util/global_utils.ts +++ b/packages/core/src/render3/util/global_utils.ts @@ -6,7 +6,7 @@ * found in the LICENSE file at https://angular.dev/license */ -/// +/// // 3p-only import {assertDefined} from '../../util/assert'; import {global} from '../../util/global'; diff --git a/packages/core/src/util/ng_i18n_closure_mode.ts b/packages/core/src/util/ng_i18n_closure_mode.ts index 7d54bcac110d..e268452ebb5e 100644 --- a/packages/core/src/util/ng_i18n_closure_mode.ts +++ b/packages/core/src/util/ng_i18n_closure_mode.ts @@ -6,7 +6,7 @@ * found in the LICENSE file at https://angular.dev/license */ -/// +/// // 3p-only import {global} from './global'; diff --git a/packages/core/src/webmcp/declare_tool.ts b/packages/core/src/webmcp/declare_tool.ts index a748020ad95e..ad940bd8ed07 100644 --- a/packages/core/src/webmcp/declare_tool.ts +++ b/packages/core/src/webmcp/declare_tool.ts @@ -6,7 +6,8 @@ * found in the LICENSE file at https://angular.dev/license */ -import type {JsonSchemaForInference} from '../../third_party/@mcp-b/webmcp-types'; +// g3-only import type {JsonSchemaForInference} from '@mcp-b/webmcp-types'; +import type {JsonSchemaForInference} from '../../third_party/@mcp-b/webmcp-types'; // 3p-only import {assertInInjectionContext, inject, Injector, runInInjectionContext} from '../di'; import type {ModelContext, ToolDescriptor} from './types'; import {DestroyRef} from '../linker'; diff --git a/packages/core/src/webmcp/provide_tools.ts b/packages/core/src/webmcp/provide_tools.ts index a9ca566bff46..0047f8a9a996 100644 --- a/packages/core/src/webmcp/provide_tools.ts +++ b/packages/core/src/webmcp/provide_tools.ts @@ -6,7 +6,8 @@ * found in the LICENSE file at https://angular.dev/license */ -import type {JsonSchemaForInference} from '../../third_party/@mcp-b/webmcp-types'; +// g3-only import type {JsonSchemaForInference} from '@mcp-b/webmcp-types'; +import type {JsonSchemaForInference} from '../../third_party/@mcp-b/webmcp-types'; // 3p-only import {EnvironmentProviders, makeEnvironmentProviders, provideEnvironmentInitializer} from '../di'; import {declareExperimentalWebMcpTool} from './declare_tool'; import type {ToolDescriptor} from './types'; diff --git a/packages/core/src/webmcp/types.ts b/packages/core/src/webmcp/types.ts index 10be83394fcc..2e8fa58c0147 100644 --- a/packages/core/src/webmcp/types.ts +++ b/packages/core/src/webmcp/types.ts @@ -6,10 +6,18 @@ * found in the LICENSE file at https://angular.dev/license */ +// g3-only-start +// import type { +// InferArgsFromInputSchema, +// JsonSchemaForInference, +// } from '@mcp-b/webmcp-types'; +// g3-only-end +// 3p-only-start import type { InferArgsFromInputSchema, JsonSchemaForInference, } from '../../third_party/@mcp-b/webmcp-types'; +// 3p-only-end /** * The client context of a given WebMCP tool execution. diff --git a/packages/forms/src/directives/shared.ts b/packages/forms/src/directives/shared.ts index 22ffaa59bcc8..ae1be2fecb99 100644 --- a/packages/forms/src/directives/shared.ts +++ b/packages/forms/src/directives/shared.ts @@ -65,7 +65,8 @@ export type SetDisabledStateOption = 'whenDisabledForLegacyCode' | 'always'; /** * Whether to use the fixed setDisabledState behavior by default. */ -export const setDisabledStateDefault: SetDisabledStateOption = 'always'; +// g3-only export const setDisabledStateDefault: SetDisabledStateOption = 'whenDisabledForLegacyCode'; +export const setDisabledStateDefault: SetDisabledStateOption = 'always'; // 3p-only export function controlPath(name: string | null, parent: ControlContainer): string[] { return [...parent.path!, name!]; diff --git a/packages/platform-browser/animations/src/module.ts b/packages/platform-browser/animations/src/module.ts index 983454e2101e..54b6a6747d99 100644 --- a/packages/platform-browser/animations/src/module.ts +++ b/packages/platform-browser/animations/src/module.ts @@ -11,7 +11,8 @@ import { Provider, ɵperformanceMarkFeature as performanceMarkFeature, } from '@angular/core'; -import {BrowserModule} from '../../index'; +// g3-only import {BrowserModule} from '@angular/platform-browser'; +import {BrowserModule} from '../../index'; // 3p-only import {BROWSER_ANIMATIONS_PROVIDERS, BROWSER_NOOP_ANIMATIONS_PROVIDERS} from './providers'; diff --git a/packages/platform-browser/src/dom/util.ts b/packages/platform-browser/src/dom/util.ts index e82aef0f463f..2fc30a775431 100644 --- a/packages/platform-browser/src/dom/util.ts +++ b/packages/platform-browser/src/dom/util.ts @@ -6,7 +6,7 @@ * found in the LICENSE file at https://angular.dev/license */ -/// +/// // 3p-only import {ɵglobal as global} from '@angular/core'; diff --git a/packages/platform-browser/testing/src/browser.ts b/packages/platform-browser/testing/src/browser.ts index 1434367bd393..b7ef62eb1e34 100644 --- a/packages/platform-browser/testing/src/browser.ts +++ b/packages/platform-browser/testing/src/browser.ts @@ -8,7 +8,8 @@ import {ɵprovideFakePlatformNavigation} from '@angular/common/testing'; import {APP_ID, createPlatformFactory, NgModule, StaticProvider, PlatformRef} from '@angular/core'; import {TestComponentRenderer} from '@angular/core/testing'; -import {BrowserModule, platformBrowser} from '../../index'; +// g3-only import {BrowserModule, platformBrowser} from '@angular/platform-browser'; +import {BrowserModule, platformBrowser} from '../../index'; // 3p-only import {DOMTestComponentRenderer} from './dom_test_component_renderer'; /** diff --git a/packages/platform-server/src/domino_adapter.ts b/packages/platform-server/src/domino_adapter.ts index d9087ef04b45..e4f1b70b1950 100644 --- a/packages/platform-server/src/domino_adapter.ts +++ b/packages/platform-server/src/domino_adapter.ts @@ -9,7 +9,8 @@ import {ɵsetRootDomAdapter as setRootDomAdapter} from '@angular/common'; import {ɵBrowserDomAdapter as BrowserDomAdapter} from '@angular/platform-browser'; -import domino from '../third_party/domino/bundled-domino'; +// g3-only import domino from 'domino'; +import domino from '../third_party/domino/bundled-domino'; // 3p-only export function setDomTypes() { // Make all Domino types available in the global env. diff --git a/packages/router/src/router_state.ts b/packages/router/src/router_state.ts index 80fbcd06c222..ec3678bf9ebd 100644 --- a/packages/router/src/router_state.ts +++ b/packages/router/src/router_state.ts @@ -240,7 +240,8 @@ export class ActivatedRoute { export type ParamsInheritanceStrategy = 'emptyOnly' | 'always'; -export const DEFAULT_PARAMS_INHERITANCE_STRATEGY: ParamsInheritanceStrategy = 'always'; +// g3-only export const DEFAULT_PARAMS_INHERITANCE_STRATEGY: ParamsInheritanceStrategy = 'emptyOnly'; +export const DEFAULT_PARAMS_INHERITANCE_STRATEGY: ParamsInheritanceStrategy = 'always'; // 3p-only /** @internal */ export type Inherited = { diff --git a/packages/types.d.ts b/packages/types.d.ts index f5d118293c65..31c2284cff5a 100644 --- a/packages/types.d.ts +++ b/packages/types.d.ts @@ -11,7 +11,7 @@ // This file contains all ambient imports needed to compile the packages/ source code /// -/// +/// // 3p-only /// // Do not included "node" and "jasmine" types here as we don't diff --git a/packages/zone.js/lib/zone.ts b/packages/zone.js/lib/zone.ts index 3a1b9ff19ba2..1d3c093d892a 100644 --- a/packages/zone.js/lib/zone.ts +++ b/packages/zone.js/lib/zone.ts @@ -31,6 +31,11 @@ declare global { const Zone: ZoneType; type Zone = _Zone; type ZoneType = _ZoneType; + + // g3-only-start + // /** This local mod is kept in place so Zone can check the NodeJS `global` variable. */ + // var global: {}; + // g3-only-end type _PatchFn = PatchFn; type _ZonePrivate = ZonePrivate; type _ZoneFrame = ZoneFrame;