Repository navigation
docs: Reserve - for stdin, guarantee review record's input shape, and say what a signal's exit code means across platforms - #353
Merged
Conversation
…ecord's input shape, and say what a signal's exit code means across platforms compatibility.md now says that a flag coming to accept a value it refuses is additive within 1.x, and fixes the meaning of one such value now: if one of the six input-file flags comes to accept -, it will read standard input, never a file named -. The deprecation policy records refusing - before 1.0, with no warning release, as its one exception to a flag keeping what it accepts through 0.x: the file stays on disk and is read as ./-. basou review record's JSON input joins basou decision capture's as a documented input shape. For a child of exec or run that a signal ended, the five fixed values are spelled out, any other signal is promised 128 plus its number on the platform basou runs on, comparable only there, with the recorded signal names saying which it was, and a signal Node has no name for is stated to be outside the promise: Node reports that child as having exited 0, so basou exits 0 too. terminal-and-import.md points session import's refusal of --from - at the reservation.
…omise, and say what review record's shape covers A refused value becomes accepted as an addition only when every invocation accepted before parses and behaves as before; making a value optional does not qualify (--file --json reads a file named --json today). Accepting one is the one way an invocation crosses zero within 1.x. The reservation of - covers an input-file flag added later too. review record's documented shape is the Input format section of its --help: fields, types, required fields and enumerated values. Whether a repos entry names a repository root follows the rule review-gaps binds with. session import's envelope is named among the input shapes, under its own rule. For a signal-ended child, only a SIGINT or SIGTERM sent to basou counts; any other ends basou before the run is recorded. The values are for POSIX platforms and a POSIX shell such as sh, bash or zsh. A signal Node has no name for is described as today's behaviour, not promised, and schemas.md says the same of command_executed. The 0.x exception names - and dates from the policy's adoption in 0.31.0. The README mentions it, and the CHANGELOG entry for the signal fix no longer says only the five values are promised.
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.
What
Policy text in
docs/spec/compatibility.md(what1.0freezes), following #351 and #352:1.xa flag may come to accept a value it refuses today, as an addition, only when every invocation accepted before parses and behaves as before; making an option's value optional does not qualify (--file --jsonreads a file named--jsontoday). Accepting a refused value is the one way an invocation crosses zero within1.x.-is reserved for standard input on every input-file flag:--file(decision capture, review record, note),--from-file(task new, session note),--from(session import), and any added later. If one comes to accept-, it reads stdin, never a file named-.basou review record's JSON input joinsbasou decision capture's. For both, the contract is theInput formatsection of--help: fields, JSON types, required fields, enumerated values. Whether areposentry names a repository root follows the rulebasou review-gapsbinds with.basou session import's envelope is named too, under its existing version rule.exec/runfor a signal-ended child. Five fixed values on every POSIX platform (129/130/131/137/143); any other signal gives 128 plus its number on the platform, as a POSIX shell reports it, comparable only on that platform, with the recordedcommand_executed.signal/received_signalnaming it. Only aSIGINTorSIGTERMsent to basou counts as basou's own; any other ends basou before the run is recorded. A signal Node has no name for (macOSSIGEMT, Linux real-time signals) reaches basou as exit0; today's behaviour is described, not promised.0.31.0), refusing-is the one exception to a flag keeping what it accepts through0.x; no warning release, because the input is a file that stays on disk and is read as./-.Also:
docs/spec/schemas.mdnotes the unnamed-signal case forcommand_executed;docs/spec/terminal-and-import.mdlinkssession import's refusal of--from -to the reservation; the README mentions the exception to the0.xfreeze; the CHANGELOG entry for #352 no longer says only five values are promised.Verification
pnpm test,pnpm lint,pnpm lint:lang,pnpm lint:paths: exit 0.compatibility.md#...anchor used in the changed files exists.status: completed,exit_code: 0and nosignal; SIGSEGV recordssignal: SIGSEGV;138is SIGBUS there.received_signalis in the publishedevent.schema.json. The JSON Schemas are unchanged.