Browse Source

Add terminology proposal summary document

Co-authored-by: tig <[email protected]>
copilot-swe-agent[bot] 1 month ago
parent
commit
99c0b730df
1 changed files with 59 additions and 0 deletions
  1. 59 0
      TERMINOLOGY_PROPOSAL_SUMMARY.md

+ 59 - 0
TERMINOLOGY_PROPOSAL_SUMMARY.md

@@ -0,0 +1,59 @@
+# Terminology Proposal Summary
+
+This is a brief summary of the [full terminology proposal](TERMINOLOGY_PROPOSAL.md).
+
+## Recommended Changes
+
+| Current Name | Proposed Name | Rationale |
+|--------------|---------------|-----------|
+| `Application.Top` | `Application.Current` | Clear, follows .NET patterns (e.g., `Thread.CurrentThread`), indicates "currently active" |
+| `Application.TopLevels` | `Application.RunStack` | Descriptive of the stack structure, pairs well with `Current` |
+| `Toplevel` class | Keep as-is (for now) | Too disruptive to rename; allow gradual evolution toward `IRunnable` |
+
+## Why These Names?
+
+### Application.Current
+- ✅ Immediately understandable
+- ✅ Consistent with .NET conventions
+- ✅ Short and memorable
+- ✅ Accurately describes the "currently active/running view"
+
+### Application.RunStack
+- ✅ Describes what it contains (running views)
+- ✅ Describes its structure (stack)
+- ✅ Works with future `IRunnable` interface
+- ✅ Clear relationship with `Current` (top of the stack)
+
+## Migration Strategy
+
+1. **Phase 1**: Add new properties, mark old ones `[Obsolete]` (no warnings initially)
+2. **Phase 2**: Update documentation and examples
+3. **Phase 3**: Refactor internal code to use new names
+4. **Phase 4**: Enable deprecation warnings
+5. **Phase 5**: Remove deprecated APIs (future major version)
+
+## Example Code
+
+```csharp
+// Before
+Application.Top?.SetNeedsDraw();
+var focused = Application.Top.MostFocused;
+
+// After
+Application.Current?.SetNeedsDraw();
+var focused = Application.Current.MostFocused;
+```
+
+## Key Benefits
+
+1. **Improved Clarity**: Names that immediately convey their purpose
+2. **Better Readability**: Code is self-documenting
+3. **Consistency**: Aligns with .NET ecosystem patterns
+4. **Future-Proof**: Works with planned `IRunnable` interface
+5. **Minimal Disruption**: Backward-compatible migration path
+
+## See Also
+
+- [Full Proposal Document](TERMINOLOGY_PROPOSAL.md) - Complete analysis and implementation details
+- Issue #4329 - Original issue requesting terminology improvements
+- Issue #2491 - Toplevel refactoring and `IRunnable` interface work