Skip to content

Document New Architecture adoption path for Fluent 2 in CONTRIBUTING.md #4057

@KlementMultiverse

Description

@KlementMultiverse

Problem

The repository has open architectural discussions (#3971, #3968) about New Architecture support and cross-platform unification, but CONTRIBUTING.md lacks a dedicated architecture decision section. New contributors and maintainers cannot quickly understand:

  1. Whether Fluent 2 components should target React Native New Architecture or legacy architecture
  2. How platform-specific code (Windows, iOS, Android, macOS) should be organized
  3. What the unification strategy is between @fluentui/react-native and platform-specific implementations
  4. When and how to deprecate Old Architecture patterns

This creates friction during code review—PRs get feedback about architectural alignment without a documented standard.

Why this matters

  • For contributors: Unclear whether to build New Arch-compatible vs. bridged components
  • For maintainers: More review cycles needed to enforce undocumented patterns
  • For the project: Risk of inconsistent implementations across platform teams
  • For adopters: No clear guidance on which architecture track to adopt

What good looks like

CONTRIBUTING.md should have an "Architecture Decisions" section that includes:

  1. Fluent 2 adoption timeline — Current target (New Arch, legacy, or both)
  2. Platform matrix — Which platforms require New Arch, which still use bridging
  3. Component migration path — How existing components transition from Old to New Architecture
  4. Code organization rules — Where platform-specific code lives (e.g., packages/components/<ComponentName>/src/native/<platform>/)
  5. Reference implementation — Link to a component that exemplifies the approved pattern

For comparison, see how React Native Windows CONTRIBUTING.md documents its New Arch adoption path.

Proposed section (example)

## Architecture Decisions

### New Architecture Support

FluentUI React Native is adopting React Native New Architecture. See [#3971](#3971) for tracking.

- **Current status:** [Alpha / In progress / Blocked by...]
- **Affected platforms:** [Windows, iOS, Android, macOS]
- **Migration timeline:** [Estimate or link to roadmap]

### Fluent 2 Unification

Components should implement Fluent 2 design tokens and be cross-platform compatible.
- Platform-specific overrides go in `src/native/<platform>/`
- Bridged code must be marked with `// @deprecated` comments linking to the New Arch alternative
- See [`packages/components/Button`](link) for a reference implementation.

Next steps

This unblocks #3971 and #3968 by creating a source of truth for architectural decisions.


Contributed by Klement Gunndu

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions