Skip to content

Commit ceb97c6

Browse files
RomainCscnRomainCscn
authored
More docs clarification (#60)
* More docs clarification * Reword continuous-vs-scheduled test for clarity Earlier wording bundled rollover into the test, but rollover is a feature of scheduled rather than the deciding factor. Reframe around whether a release needs to exist as a thing before it ships.
1 parent 024302d commit ceb97c6

2 files changed

Lines changed: 18 additions & 11 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -149,16 +149,16 @@ linear-release update --stage="in review" --name="Release 1.2.0"
149149

150150
### CLI Options
151151

152-
| Option | Commands | Description |
153-
| ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
154-
| `--name` | `sync`, `complete`, `update` | Custom release name. For `sync`, the value is applied to the targeted release — both newly created releases and existing ones get the provided name. For `complete` and `update`, sets the name on the targeted release. |
155-
| `--release-version` | `sync`, `complete`, `update` | Release version identifier. For `sync`, defaults to short commit hash. For `complete` and `update`, if omitted, targets the most recent started release. |
156-
| `--stage` | `update` | Target deployment stage (required for `update`) |
157-
| `--include-paths` | `sync` | Filter commits by changed file paths |
158-
| `--json` | `sync`, `complete`, `update` | Output result as JSON |
159-
| `--quiet` | `sync`, `complete`, `update` | Only print errors |
160-
| `--verbose` | `sync`, `complete`, `update` | Print detailed progress including debug diagnostics |
161-
| `--timeout` | `sync`, `complete`, `update` | Max duration in seconds before aborting (default: 60) |
152+
| Option | Commands | Description |
153+
| ------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
154+
| `--name` | `sync`, `complete`, `update` | Custom release name. For `sync`, the value is applied to the targeted release — both newly created releases and existing ones get the provided name. For `complete` and `update`, sets the name on the targeted release. |
155+
| `--release-version` | `sync`, `complete`, `update` | Release version identifier. For `sync`, defaults to short commit hash. For `complete` and `update`, selects an existing release with that version (errors if none exists); does not change a release's version. If omitted, targets the most recent started release. |
156+
| `--stage` | `update` | Target deployment stage (required for `update`) |
157+
| `--include-paths` | `sync` | Filter commits by changed file paths |
158+
| `--json` | `sync`, `complete`, `update` | Output result as JSON |
159+
| `--quiet` | `sync`, `complete`, `update` | Only print errors |
160+
| `--verbose` | `sync`, `complete`, `update` | Print detailed progress including debug diagnostics |
161+
| `--timeout` | `sync`, `complete`, `update` | Max duration in seconds before aborting (default: 60) |
162162

163163
### Command Targeting
164164

@@ -217,11 +217,14 @@ Path patterns can also be configured in your pipeline settings in Linear. If bot
217217
4. **Detects pull request numbers** from commit messages (e.g., `Merge pull request #42`)
218218
5. **Syncs data to Linear** that adds issues to a newly created completed release (continuous pipelines) or the currently in-progress release (scheduled pipelines)
219219

220+
**First sync**: when no prior release exists for the pipeline, only the current commit is scanned (there's no previous SHA to bound the range from).
221+
220222
## Troubleshooting
221223

222224
- **Unexpected release was updated/completed**: pass `--release-version` explicitly so the command does not target the latest started/planned release.
223225
- **No release created by `sync`**: if no commits match the computed range (or path filters), `sync` returns `{"release":null}`.
224-
- **Stage update fails**: verify stage name exactly. If stage names normalize to the same value, use the exact stage name to avoid ambiguity.
226+
- **Stage update fails**: `--stage` matches first by exact name, then case-insensitively with dashes and underscores treated as spaces. If multiple stages normalize to the same value, pass the exact stage name to disambiguate.
227+
- **`sync --release-version` fails because the matching release is archived**: restore the archived release in Linear before re-syncing.
225228
- **Operation timed out**: the CLI aborts after 60 seconds by default. For large repositories or slow networks, increase the limit with `--timeout=120`.
226229
- **`git` not on PATH**: the CLI shells out to `git`. Install it in your CI image (e.g. `apt-get install -y git` on Debian/Ubuntu).
227230
- **No `.git` directory found**: the CLI must run inside a full clone. On GitLab CI, set `GIT_STRATEGY: clone` (not `none` or `empty`) and `GIT_DEPTH: 0` on the linear-release job.

‎skills/linear-release-setup/SKILL.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ Ask, in order:
3333
- **Continuous** — every deploy completes a release. Typical for nightlies, dogfood, and web apps that ship on merge.
3434
- **Scheduled** — releases collect changes over time and move through stages before shipping. Typical for versioned mobile and on-prem.
3535

36+
**The test:** does the team need to track a release before it ships — naming it, seeing what's queued in it, or moving it through phases (code freeze, QA, etc.)?
37+
- Yes → **scheduled** (the release exists as an in-progress thing before it ships).
38+
- No → **continuous** (the release is created at the moment of shipping).
39+
3640
4. **For each scheduled pipeline, ask explicitly:**
3741
- **Branch model** — just `main`, or `main` + release branches (`release/*`)?
3842
- **Version source** — calendar (`2026.05`), semver (`1.2.0`), or commit SHA? Derived from branch name, CI variable, file, or git tag?

0 commit comments

Comments
 (0)