Skip to content

[nx-migration]- spilt milestone #4159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Chloe_he (Chloe-He) wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[nx-migration]- spilt milestone #4159

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .claude/settings.local.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"permissions": {
"allow": [
"Bash(find:*)",
"WebFetch(domain:nx.dev)",
"Bash(.specify/scripts/bash/create-new-feature.sh:*)"
]
},
"enabledMcpjsonServers": [
"mcp-atlassian",
"chrome-devtools",
"new-relic-mcp-server"
]
}
16 changes: 16 additions & 0 deletions .mcp.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"mcpServers": {
"mcp-atlassian": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
},
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
},
"new-relic-mcp-server": {
"type": "http",
"url": "https://mcp.newrelic.com/mcp/"
}
}
}
38 changes: 38 additions & 0 deletions specs/003-nx-migration/checklists/requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Specification Quality Checklist: Nx Migration

**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2026-01-27
**Feature**: [spec.md](./spec.md)

## Content Quality

- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed

## Requirement Completeness

- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified

## Feature Readiness

- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification

## Notes

- Spec is ready for `/speckit.clarify` or `/speckit.plan`
- Open questions (Q1-Q3) are planning/timeline questions, not spec clarifications
- Blockers are documented for investigation during implementation
- All 9 milestones have verification criteria to ensure non-breaking deployments
- **Updated 2026-01-27**: Removed `nx release` milestone (M7) per user request - existing release process will be preserved
100 changes: 100 additions & 0 deletions specs/003-nx-migration/milestones/M1-nx-initialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# M1: Nx Initialization

**Priority**: P1 (Critical Path)
**Est. Effort**: Very Low
**Complexity**: Small
**Status**: Required

## Overview

Initialize an Nx workspace in the existing Backpack repository to enable task orchestration, caching, and dependency graph features.

## Why This Milestone?

### Strategic Context

Nx has been selected as Skyscanner Web's strategic monorepo tooling. Initializing Nx in Backpack is the first step toward:

- **Faster CI/CD**: Leveraging Nx's computation caching and affected commands
- **Better DX**: Visualizing the dependency graph and understanding project relationships
- **Future-proofing**: Aligning with the broader Skyscanner web ecosystem

### Why We Need Each Step

| Step | Why It's Needed |
|------|-----------------|
| Run `npx nx@latest init` | This is Nx's official bootstrapping command that analyzes existing workspace tooling and creates appropriate configuration |
| Verify `nx.json` created | Confirms Nx is properly initialized and can recognize the workspace |
| Test `nx graph` | Validates that Nx can analyze the project structure and dependencies |
| Verify existing scripts work | **Critical**: Ensures zero disruption to current workflows - developers and CI continue working unchanged |
| CI pipeline passes | Confirms the change is production-safe and can be merged |

### What Happens If We Skip This?

Without Nx initialization, we cannot:
- Use `nx affected` to run only changed projects
- Enable computation caching
- Enforce module boundaries
- Visualize the dependency graph

This is the **foundation** for all subsequent milestones.

---

## User Story

As a Backpack maintainer, I want to initialize an Nx workspace in the existing repository so that I can start leveraging Nx's task orchestration, caching, and dependency graph features incrementally.

---

## Acceptance Scenarios

1. **Given** the Backpack repository, **When** `npx nx@latest init` is run, **Then** an `nx.json` configuration file is created at the root

2. **Given** Nx is initialized, **When** `nx graph` is executed, **Then** a dependency visualization is displayed

3. **Given** Nx is initialized, **When** existing `npm run build` is executed, **Then** the build completes successfully as before

4. **Given** Nx is initialized, **When** CI workflows run, **Then** all existing tests and checks pass without modification

---

## Verification Criteria

- [ ] `nx.json` exists at repository root
- [ ] `nx graph` command produces output
- [ ] All existing `npm run` scripts work unchanged
- [ ] CI pipeline passes (no breaking changes)
- [ ] No changes to consumer import paths

---

## Risks to Monitor

| Risk | Impact | Mitigation |
|------|--------|------------|
| Nx plugin peer dependency conflicts | CI/local build failures | Review dependency tree before committing; test in isolated branch |
| TypeScript `composite: true` conflicts | Build errors, missing `.d.ts` files | Keep composite disabled initially; investigate in separate spike if needed |

---

## Rollback Plan

If issues arise:
1. Revert the commit that adds `nx.json` and related config
2. Remove `nx` from `devDependencies`
3. CI and local development return to previous state

---

## Dependencies

- None (this is the first milestone)

## Blocks

- M2: Project Structure Confirmation
- M3: Storybook Colocation
- M4: Components as Nx Projects
- M5: Static Checks via Nx
- M6: Module Boundaries
138 changes: 138 additions & 0 deletions specs/003-nx-migration/milestones/M2-project-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# M2: Project Structure Confirmation

**Priority**: P1 (Critical Path)
**Est. Effort**: Low
**Complexity**: Small
**Status**: Required

## Overview

Define and align on a target project hierarchy that integrates well with Platform Engineering standards and enables proper dependency graph analysis.

## Why This Milestone?

### Strategic Context

Before moving any code, we need a clear destination structure. This milestone is primarily **planning and alignment**, not implementation. The decisions made here affect every subsequent milestone.

### Why We Need Each Step

| Step | Why It's Needed |
|------|-----------------|
| Create draft structure document | Documents the mapping from current ~92 component folders to target locations; serves as the source of truth for migration |
| Align with PE and web-enablement | Ensures the structure complies with TypeScript Monorepo Production Standard and won't need to be re-done later |
| Consider internal reorganization | Decides whether components' internal folder structure (e.g., V2 subdirectories) should also change |
| Update configurations | Jest, Storybook, GitHub Actions all reference file paths - they must be updated together to avoid broken builds |

### What Happens If We Skip This?

Without structure confirmation:
- Teams may disagree on where files should live, causing rework
- Structure may not comply with Production Standard, requiring future refactoring
- Dependency graph analysis may be inaccurate
- Other milestones will lack a clear target state

### Current vs Target Structure

**Current**:
```
packages/
├── bpk-component-button/
├── bpk-component-card/
├── bpk-mixins/
├── bpk-stylesheets/
└── ... (~92 packages)
examples/
├── bpk-component-button/
│ └── stories.tsx
└── ...
```

**Target** (to be confirmed):
```
packages/
├── bpk-component-button/
│ ├── src/
│ │ ├── BpkButton/
│ │ └── stories.tsx (colocated)
│ ├── project.json (Nx project config)
│ └── tsconfig.*.json (TypeScript configs)
└── ...
```

---

## User Story

As a Backpack architect, I want to define and align on a target project hierarchy so that the migration has a clear destination structure that integrates well with Platform Engineering standards and enables proper dependency graph analysis.

---

## Acceptance Scenarios

1. **Given** the current Backpack structure, **When** a draft structure document is created, **Then** it maps all ~92 component folders to their target locations

2. **Given** the draft structure, **When** reviewed by PE and web-enablement teams, **Then** alignment is confirmed

3. **Given** alignment is confirmed, **When** folder reorganization begins, **Then** the changes follow the approved structure exactly

4. **Given** folders are moved, **When** GitHub Actions, Jest config, and Storybook entries are updated, **Then** all automation works with new paths

---

## Verification Criteria

- [ ] Draft project structure document exists and is approved
- [ ] Structure aligns with TypeScript Monorepo Production Standard
- [ ] All component folders mapped to target locations
- [ ] CI pipeline passes after folder moves
- [ ] Storybook builds successfully with new structure
- [ ] No changes to consumer import paths (`@skyscanner/backpack-web/...`)

---

## Deliverables

1. **Project Structure Document**: A detailed mapping of current → target locations
2. **Configuration Updates**: Changes to Jest, Storybook, GitHub Actions
3. **Migration Script** (optional): Automated tooling to move files consistently

---

## Key Decisions Required

| Decision | Options | Recommendation |
|----------|---------|----------------|
| Keep `packages/` as root? | Yes / Move to `libs/` | Keep `packages/` to minimize consumer impact |
| Internal component structure? | Keep as-is / Standardize | Defer to M3/M4 |
| Handle `bpk-mixins` differently? | Same as components / Special case | Special case (shared utilities) |

---

## Risks to Monitor

| Risk | Impact | Mitigation |
|------|--------|------------|
| Disagreement on structure | Delays all subsequent milestones | Schedule alignment meeting early; document decisions |
| Consumer import path changes | **Breaking change** | Verify import paths are preserved via build output |
| Configuration drift | Some tools work, others fail | Test all configurations together in single PR |

---

## Rollback Plan

If structure is approved but implementation fails:
1. Revert file moves via `git revert`
2. Revert configuration changes
3. Revisit structure document with lessons learned

---

## Dependencies

- M1: Nx Initialization (Nx must be installed to use `nx workspace:move`)

## Blocks

- M3: Storybook Colocation (needs target locations defined)
- M4: Components as Nx Projects (needs final structure)
Loading
Loading