build(client): introduce build task naming guidelines#25730
build(client): introduce build task naming guidelines#25730tylerbutler wants to merge 3 commits intomicrosoft:mainfrom
Conversation
github-actions
bot
added
area: dds
There was a problem hiding this comment.
Leave feedback here about the task names or the translation from old name to new name. I don't love the placement of the -ci in the CI tasks for example.
|
🔗 Found some broken links! 💔 Run a link check locally to find them. See linkcheck output |
|
I made an alternative plan that I like a little better. Alternative Naming Scheme: Colon for Orchestrators, Dash for ExecutorsComparison: Current PR vs Proposed AlternativeSummary of ApproachCurrent PR: Remove category prefixes from executors entirely
Proposed Alternative: Keep category prefixes, use dash separator for executors
Naming RulesOrchestrators (use colon
Executors (use dash
Rename Mapping Comparison
Key Advantages of Proposed Alternative1. Preserves Category Context# Current PR - loses context
npm run esnext # Is this a build? test? check?
npm run coverage # Related to what?
# Proposed - maintains context
npm run build-esnext # Clearly a build executor
npm run test-coverage # Clearly a test executor2. Better Task Discovery# List all build-related executors
npm run build-<tab>
build-esnext
build-test-cjs
build-test-esm
build-api-reports-current
build-copyfiles
build-generate-version
# List all check-related executors
npm run check-<tab>
check-biome
check-attw
check-exports-cjs-legacy
check-release-tags3. Consistent Category-First Ordering# Current PR - inconsistent ordering
npm run biome-check # tool-category (reversed)
npm run esnext # no category
npm run tsc-test-cjs # tool-category-variant
# Proposed - always category-first
npm run check-biome # category-tool
npm run build-esnext # category-tool
npm run build-test-cjs # category-subcategory-variant4. Clear Visual Distinction
5. Simpler Mental Model6. Reduced Namespace Pollution# Current PR - top-level namespace gets crowded
esnext, coverage, attw, copyfiles, biome-check, ...
# Proposed - top-level reserved for workflows only
build, test, lint, check, start
└─ Everything else is categorized with prefix7. Easier Migration# Most renames are simple character substitution
sed 's/build:esnext/build-esnext/g'
sed 's/check:biome/check-biome/g'
sed 's/test:coverage/test-coverage/g'
# Not structural reorganization like:
build:esnext → esnext (remove category entirely)
check:biome → biome-check (reverse order)Special Cases & DecisionsMulti-level tasks (3+ colons)Current: Recommendation: Use Option 1 (all dashes) for consistency - these are all executors. Tool variants (modes/flags)Current: Recommendation: Use Option 2 ( Standalone tools (no ambiguity)Tasks like: Tasks that are actually orchestratorsExample: This is actually an orchestrator (coordinates doc generation), not an executor! Implementation Notes
Questions for Discussion
|
|
I didn't look at all the details, but I think "esnext" is a very poor way to say ESM, since esnext typically refers to an upcoming standard and thus involves non standardized APIs and such. The esm build is the one actually using standard modules, and has been incorrect to call esnext since ES6 was standardized in 2015 (10 years ago!). If we want to do renames, that should be fixed. build:test:mocha:esm already uses "esm": the build should align with that. |
Agreed. The esnext name hasn't been accurate for a long time. |
That sounds to me like all orchestrator scripts in package.json should be |
|
This PR has been automatically marked as stale because it has had no activity for 60 days. It will be closed if no further activity occurs within 8 days of this comment. Thank you for your contributions to Fluid Framework! |
3 participants
Task Naming Convention
Orchestrators just define dependencies - executors just execute work. While we can have arbitrary levels of orchestration, too many gets hard to reason about, and only two seem useful.
Workflow Orchestrators: Single word, no colons
build(builds everything)test(runs all tests)lint(runs all linters)check(runs all checks) (checks don't require a build while tests do)start,test) remain at this tier even if occasionally used as executorsStage Orchestrators: Semantic category names with single colon
build:compile(compiles to all output formats)build:api(generates API documentation)test:unit(runs unit tests in all formats)Tool Executors: Two naming patterns
tsc,eslint,jest,esnext,coverage(tool names or semantic operations)tsc,jest,esnext,coveragegenerate-version,api-reports-current(dash-separated)esnext-experimental,tsc-test-cjs(dash-separated for different purposes)tsc:watch,jest:verbose(tool + mode/flag with colon separator)Decision Framework for Task Classification
When classifying or renaming a task, follow this decision tree:
Step 1: Analyze Classification Percentage
Step 2: Determine Executor Naming Pattern
Step 2.5: Dash vs Colon Decision
When to use DASH (Pattern A):
generate-version,api-reports-currentesnext-experimental(different entry point),tsc-test-cjs(different file set)When to use COLON (Pattern C):
tsc:watch,jest:verboseExamples:
esnext-experimental✓ (dash) - Different entry point configuration = different purposejest:verbose✓ (colon) - Same jest tool with --verbose flag = mode changeapi-reports-current✓ (dash) - Different API level configuration = different purposetsc:watch✓ (colon) - Same tsc tool with --watch flag = mode changeStep 3: Pattern Family Consistency Check
Simplified Decision Logic