This document is meant to serve as a rudimentary introduction to the set up and use of Yarn Workspaces in vets-website.

In this documentation, references to src/platform are meant to indicate the repository directory vets-website/tree/main/src/platform; similarly, src/applications indicates vets-website/tree/main/src/applications

What is a workspace

Yarn Workspaces is a feature that allows users to install dependencies from multiple package.json files in subfolders of a single root package.json file, all in one go. Yarn can also create symlinks between Workspaces that depend on each other, which will ensure the consistency and correctness of all directories.

Put simply, a workspace is a package of managed code.

Glossary:

Term

Definition

Workspace

A directory denoted via a valid package.json file.

Example:
src/applications/vaos... containing a package.json file such as:

{ 
  "name": "@department-of-veterans-affairs/applications-vaos",
  "version": "0.0.1",
... 
  "private": true
}
CODE

See: workpaces definition on the Yarn Documentation site

Worktree

A valid workspace at the root of vets-website that has a workspaces field in its package.json file, which connects it in some way to project-level package.json files.

Example:
In the root directory of vets-website, we have a package.json file such as:

{ 
  "name": "vets-website",
  "version": "0.0.1",
...
  "workspaces": [ "src/applications/vaos", ... ],
  "private": true
}
CODE

See: worktree definition on the Yarn Documentation site

Worktree Maintainer
*Only Release Tools Team

A worktree maintainer’s function is to ensure the health of the overall worktree, perform the initial set up of workspaces, consult with workspace maintainers, and deal with any issues stemming from the use of workspaces that affect the repo globally.

Workspace Maintainers
*VFS or Platform Engineers

A workspace maintainer’s function the maintenance (not set up) of the workspace(s) specifically corresponding to their team's projects. This may entail tasks such as: managing dependencies, managing their apps entries in the nohoist field, writing scripts, curating entry points, etc.

User roles

Users can be categorized into two types: worktree maintainers and workspace maintainers.

The Release Tools team serves as the worktree maintainers. They, exclusively, define, set up and trouble shoot issues with the worktree. Release Tools sets up new workspaces for eligible teams. Release Tools also assists in maintaining workspaces within src/platform.

Workspace maintainers are members of app teams (VFS or Platform) that maintain the pre-existing workspaces corresponding to their own team's projects.

Release Tools has set up the existing child directories of src/platform as workspaces. As such, all Platform teams can be considered workspace maintainers by default.

Please consult the Workspace Maintenance: Overview.

If you are part of Release Tools you should familiarize yourself with both the Workspace Maintenance: Overview and the Worktree and Workspace Setup Guide.