docs: update glab stack docs to clarify concepts and unify terminology

Description

This MR:

  • Updates the glab stack command docs and user-facing text to use the same terminology:
    • Stacked diffs for the feature as a whole.
    • A stack of diffs for one stack, not a 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 😓
    • Diff for a single item in a stack.
      • I saw entry, layer, revision, and stack item across these docs 😅
  • Clarifies that glab stack move picks a diff in the stack, and glab stack switch picks 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 save and amend to 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 by current and how that compares to checked out. It seems clearer to just drop this phrase. I used checked out instead because each diff has its own branch.
  • Fixes a few other inaccuracies that 🤖 found during review, for example:
    • sync doesn't remove diffs with closed merge requests.
    • reorder retargets merge requests straight away.
    • create makes an empty stack, not a diff.
  • Some style guide edits, like ensuring the Long and Short don'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.

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

Merge request reports

Loading
Loading