ZcashFoundation/parity-zcash

Standardize Github Actions `jobs.<job_id>.steps` indentation

zancas opened this issue · 1 comments

zancas commented

I am studying this workflow file:

https://github.com/ZcashFoundation/zebra/blob/5ade2a86f83fc7e0907d70524c5575f6f9ad162a/.github/workflows/push.yml

using this workflow "Log view":

https://github.com/ZcashFoundation/zebra/pull/163/checks?check_run_id=203489646

I am confused by the indentation style used to denote a sequence of jobs.<job_id>.steps. I suspect my confusion stems from the inconsistency in the Github Actions documentation for "steps".

For example, within one screen-full of examples there are 3 different indentation conventions in use:

  1. "-" in the "s"-in-"steps" column
  2. "-" indented one space from "s"-in-"steps" column
  3. "-" indented two spaces from "s"-in-"steps" column

Obviously these are all valid YAML, and the inconsistency is to be expected in a beta project, but I doubt there's much benefit to having so much variance in the documentation, and In My Opinion it decreases readability.

It'd be neat if Zebra enforced a strict standard and perhaps even proposed it to upstream Github Actions.

Why not enforce a 1-space indentation for the elements of a jobs.<job_id>.steps sequence?
Plausibly my attraction to this format is due to my long exposure to the semantically significant white-space of Python.

Actually in the course of creating this issue, I have realized that the authors of the jobs.<job_id>.steps document made exactly the error in the documentation, that I was making trying to read the file.. which might explain why I was confused... the docs are wrong.

The document incorrectly asserts that, for example, id is a property of steps:
https://help.github.com/en/articles/workflow-syntax-for-github-actions#jobsjob_idstepsid

That's not correct. The id is a property of an individual step within the sequence of steps.
I think the fact that the documentation authors made the error of conflating the properties of a step with the properties of steps argues in favor of enforcing a differentiating (Python-like) indentation style.

Readability is high a high priority desideratum. <--(Okay, maybe I stretched a bit for that. ;) )