Skip to content

Add integrated architectural documentation for contributors #314854

@Martincive

Description

@Martincive

VS Code has a well-structured modular architecture with multiple layers, runtimes and extension hosts. However, understanding how these components relate to each other requires navigating several independent documentation sources.

For contributors who are new to the repository, building a complete mental model of:

  • architectural layers
  • runtime partitions
  • extension host behavior
  • environment-specific execution contexts
  • tooling and build scripts

can be challenging.

Proposal:
Introduce an integrated architectural documentation section aimed specifically at contributors.

This documentation could include:

  • high-level architecture diagrams
  • relationships between layers and runtimes
  • mapping between components and tooling/scripts
  • explanations of how changes impact different execution environments

Potential benefits:

  • reduce cognitive complexity for onboarding contributors
  • improve maintainability knowledge sharing
  • make architectural decisions easier to understand
  • improve contributor awareness of system-wide impact

The proposal focuses on improving accessibility of existing architectural knowledge rather than changing the architecture itself.

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions