architecture: Explain codebase change paths#182
Merged
Conversation
The project has a root architecture document that surveys package roles, session state, staging behavior, and named-batch internals. Contributors must infer how a user action moves between modules, where a change belongs, and which supporting surfaces need updates when behavior is added or removed. This commit addresses that by following status and include through their current functions, mapping directory responsibilities, and providing concrete addition and removal checklists. Subsequent commits will move named-batch detail into its own reading path and make both guides easier to discover.
The codebase guide now directs advanced named-batch work to a separate internal reference. That reference describes storage, ownership, display, merge, and source refresh in one long survey. Contributors entering the reference must learn several internal terms before their meanings are defined, then infer how user commands cross the command and batch packages. This commit addresses that by defining stored concepts first, tracing each batch operation through its current starting points, and grouping change guidance by responsibility rather than module inventory. Subsequent commits will make the implementation guides discoverable from contributor entry points and align contribution terminology with their writing rules.
The contributor guide documents development setup and commit construction. The repository now has separate implementation guides for ordinary commands and named batches. Contributors who begin with the contribution instructions must discover those implementation guides elsewhere, including the boundary that determines when batch internals are relevant. This commit addresses that by adding a source-navigation section that links both guides and states when each one applies. Subsequent commits will align contribution terminology with that guidance and expose the guides from the repository overview.
The contribution guide uses abbreviated interface and translation terms throughout its rules and examples. Readers must supply meanings such as CLI, TUI, AI, POT, and RHEL even though the guide asks contributors not to rely on unexplained internal labels. This commit addresses that by spelling out those terms wherever they appear in contributor instructions and message examples. The final commit will expose the implementation guides from the repository overview.
The repository overview links user documentation and directs contributors to the contribution guide. Readers evaluating the source tree cannot discover the ordinary codebase guide or the separate named-batch reference from that overview. This commit addresses that by listing both implementation guides in the contributing section. The repository now provides an introductory implementation path, a separate batch reference, and links to both from its contributor entry points.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The architecture documentation previously presented the source tree as a broad directory survey, while named-batch behavior appeared alongside the introductory material.
Contributors had to infer how a command moves through parsing, dispatch, coordination, Git operations, and output. They also lacked stable guidance for deciding where a feature change belongs or which supporting surfaces need corresponding updates.
This pull request addresses that by following ordinary command paths through their participating modules, describing directory responsibilities, and adding checklists for adding or removing a command or source slice. It moves the sizable named-batch explanation into a separate guide and links both guides from the contributor entry points.
The contributor guidance also spells out interface, translation, platform, and artificial-intelligence abbreviations so readers do not need prior knowledge to interpret its rules and examples.
The documentation now provides an introductory path for ordinary changes, an isolated reference for named-batch internals, and stable discovery links that do not depend on exact module counts.
Validation included the architecture-boundary test suite, a strict documentation build, local-link checks, and whitespace-error checks.