Terminology around "kill"

[lnhsingh]

Related to #7755.

I've made update to our docs to adhere to our new Inclusive Language guide (modeled after Google's), and one of the guidelines is to "avoid using overly violent language." In our docs, we sometimes use "kill" as a synonym for terminate, end, stop, shut down, etc. However, after chatting with @jordanlewis, it quickly became apparent that the terminology we use is nuanced and changes depending on the context.

In general:

• Terminate means "instantly turn off, without regard to process (i.e., unorderly). Use "terminate" as a synonym for "kill". Keeping our Inclusive Language guide in mind, "terminate" should be used where possible instead of "kill".
• Shut down, stop, or end means "turn off in an orderly fashion".

Examples:

• "pkill is a command that can be used to send a signal to a process."
• "pkill -9 is a command that can be used to terminate a process."
• "If the node is running in the background and you are not using a process manager, send a signal to the cockroach process to terminate it."
• "Step 1. Terminate the process: pkill cockroach [...]
• "To simulate node failure, terminate one of the CockroachDB nodes: $ kubectl delete [...]"
• "A node will shut down if the mean offset of its clock from the other nodes' clocks exceeds 80% [...]"
• "When you see a query that is taking too long to complete, you can use the CANCEL QUERY statement to stop it."

To do:

• Update docs according to these nuances (once approved / agreed upon)
• Update the Inclusive Language Guide to reflect these nuances

[lnhsingh]

@bdarnell - can you review / confirm that this is correct? Are you ok with this change (mainly, do you agree that "terminate" is synonymous with "kill")? Would appreciate any feedback you have.

[jordanlewis]

"pkill is a signal that is used to terminate a process."

Just for clarity, pkill and kill are actually Linux commands that let you send any signal to a process, not just termination signals.

[lnhsingh]

Thanks for the clarification @jordanlewis - updated the examples.

[bdarnell]

The historical unix terminology here is a mess, and not just because of the unnecessary violence.

• kill and pkill are commands used to send signals to processes.
• By default, the kill commands send the terminate signal SIGTERM, which gives the process an opportunity to shut down gracefully. This is the most common informal meaning of "killing" a process.
• Optionally (with kill -KILL or kill -9, the latter of which is for some reason used more commonly), the kill commands can send the kill signal SIGKILL, which is an immediate non-orderly termination of the process.
• There is also a stop signal SIGSTOP which pauses a process in place, so that it can be restarted with a continue signal SIGCONT. It's a bad idea to ever use SIGSTOP on a cockroach process; I mention this just because it means that "stop" also has some baggage in this context.

So "kill" can mean either graceful or abrupt termination depending on the context. As far as official usage in the signal commands go, "terminate" is for graceful termination, but as I've demonstrated several times so far in this message it's often used to cover any kind of end to the process. I think "terminate" is the best replacement for "kill" in most cases in our docs.

So going through your examples:

• "pkill is a signal that is used to terminate a process." -> "pkill is a command used to send a signal to a process" or "pkill is a command used to to terminate a process" (if we're talking about it in the context of terminating processes. But IIRC once some of @taroface 's work is done the only remaining uses of pkill will using a different signal for certificate reloading, not for termination)
• "If the node is running in the background and you are not using a process manager, send a signal to the cockroach process to terminate it." 👍 Could be more specific: send a SIGTERM signal to the cockroach process.
• "Step 1. Terminate the process: pkill cockroach [...]" 👍
• "To simulate node failure, terminate one of the CockroachDB nodes: $ kubectl delete [...]" 👍 I might use "delete" here to match the kubectl command, but "delete" in this context sounds odd to me. In other cases (such as when we're talking about systemctl stop), I might say "stop" instead of "terminate"
• "A node will shut down if the mean offset of its clock from the other nodes' clocks exceeds 80% [...]" 👍
• "When you see a query that is taking too long to complete, you can use the CANCEL QUERY statement to stop it." 👍

[lnhsingh]

Thanks for the insight @bdarnell! I'll make additional edits with all this in mind.