Loading
docs: update glab stack docs to clarify concepts and unify terminology
Description
This MR:
- Updates the
glab stackcommand docs and user-facing text to use the same terminology:Stacked diffsfor the feature as a whole.A stack of diffsfor one stack, nota stacked diff. The latter means a single diff in a stack.- This confused me a lot and made it hard for me to understand the context and scope of these commands
😓
- This confused me a lot and made it hard for me to understand the context and scope of these commands
Difffor a single item in a stack.- I saw
entry,layer,revision, andstack itemacross these docs😅
- I saw
- Clarifies that
glab stack movepicks a diff in the stack, andglab stack switchpicks a stack. The two pages now point to each other. - Explains what a stack of diffs is and how a stack relates to stacked merge requests in GitLab after you run
glab stack sync. - Points
saveandamendto each other, so it's clear when to use each. - Stops using the phrase
current stack, a phrase that the CLI never shows to users. I had a lot of questions about what we mean bycurrentand how that compares tochecked out. It seems clearer to just drop this phrase. I usedchecked outinstead because each diff has its own branch. - Fixes a few other inaccuracies that
🤖 found during review, for example:syncdoesn't remove diffs with closed merge requests.reorderretargets merge requests straight away.createmakes an empty stack, not a diff.
- Some style guide edits, like ensuring the
LongandShortdon't repeat each other.
After we merge this, I'll do a companion MR to the user docs in gitlab. I'll also add an entry to the style guide for these terms.
Related issues and merge requests
Docs: clarify stacked diffs vs stacked MRs, and... (#8558 - closed)
Documentation
If this MR adds or updates CLI command documentation, follow the conventions in the
GitLab CLI (glab) documentation style guide,
run make gen-docs, and commit the updated files in docs/source/.
Edited by Uma Chandran - OOO until Nov 6