Actions: Indicate that .steps is an array of objects

[Simran-B]

Why:

The headlines for job steps like jobs.<job_id>.steps.name imply the following YAML:

jobs:
  <job_id>:
    steps:
      name: Name

However, steps is actually an array of objects (note the hyphen):

jobs:
  <job_id>:
    steps:
      - name: Name

This should be indicated, e.g. like jobs.<job_id>.steps.*.name.

What's being changed:

Use .* to reflect that steps is an array. This is consistent with Object filters. It could be misinterpreted as shown below however:

jobs:
  <job_id>:
    steps:
      something:
        name: Name

Alternative ways to express it that come to mind:

• steps[*].name (JSONPath style)
• steps[].name (jq style)

Also fix angled bracket in headline outputs.<output_id.value>. already fixed by #1456

Check off the following:

• All of the tests are passing.
• I have reviewed my changes in staging.
  • https://docs-1385--actions-array-path.herokuapp.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsid
  • https://docs-1385--actions-array-path.herokuapp.com/en/free-pro-team@latest/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsrun
  • https://docs-1385--actions-array-path.herokuapp.com/en/free-pro-team@latest/actions/creating-actions/metadata-syntax-for-github-actions#outputsoutput_idvalue
• For content changes, I have reviewed the localization checklist
• For content changes, I have reviewed the Content style guide for GitHub Docs.

[janiceilene]

@Simran-B Thanks so much for opening a PR! I'll get this triaged for review 🌟

[github-actions]

This PR is stale because it has been open 7 days with no activity and will be automatically closed in 3 days. To keep this PR open, update the PR by adding a comment or pushing a commit.

[janiceilene]

Thanks for your patience @Simran-B! Our small team is working our way through reviewing all of the amazing contributions ✨

[Simran-B]

No pressure, I'm in a very similar position myself, so I can totally relate.

BTW. I edited my initial post: jobs.<job_id>.steps.*.name could be misinterpreted and I'm actually in favor of jq's syntax jobs.<job_id>.steps[].name after some more thought.

[shati-patel]

(Just for information: I updated this PR from main to fix merge conflicts that came from #1389. I'll let someone from the Ecosystem docs team take a look at the actual changes, since they're more familiar with these topics!)

[github-actions]

This PR is stale because it has been open 7 days with no activity and will be automatically closed in 3 days. To keep this PR open, update the PR by adding a comment or pushing a commit.

[lucascosti]

Thanks a lot for this PR, @Simran-B! Sorry it's taken us a while to respond.

IIUC, there's no standard specification for referring to a path for a yaml key (please correct me if I'm wrong! 🙂 )

I edited my initial post: jobs.<job_id>.steps.*.name could be misinterpreted

🤔 Yep, I agree with this. * could mean any item under steps, not specifically an array.

I think I would prefer using yq's syntax for referring to an array path: jobs.<job_id>.steps[*].name. However, That's just my personal opinion.

I will raise this in our team meeting this week to see if there's consensus in the team on what we should use. Stay tuned, I'll come back with an answer!

[Simran-B]

Correct, there is not a single standard and both JSONPath and jq are about JSON, not YAML. On the other hand, YAML is a superset of JSON, so it's not too far off.

I like the idea of using [*]. as in yq, a true YAML tool. Since we are both not fond of .*, I'll update the PR to the currently preferred solution and am looking forward to the outcome of your team discussion,

[lucascosti]

We discussed it internally, and we decided that the yq convention is probably the best for now. The good thing is that adding/removing special characters from the headings doesn't change the anchor URLs, so we don't have to worry about links breaking with any of these changes. 🥳

[lucascosti]

Thanks soooo much, @Simran-B for this marvelous work! 🙇‍♂️ This will help people understand the syntax a lot better than the misleading paths we have at the moment!

This looks great, so I'll merge it in! 🚢

[github-actions]

Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours.

[Simran-B]

Thanks @lucascosti!

The good thing is that adding/removing special characters from the headings doesn't change the anchor URLs

It struck me this morning that I didn't check whether it would break existing anchor links. Great to hear that it doesn't!

Is there a policy how to handle cases where links do get broken? Should one add <a name="former-anchor-slug"></a>? I find examples of that in two files. This seems to be preferred over <a id="..."/> and <a id="..."></a>.

On another related note, is it worth to look into avoiding trailing hyphens in anchor slugs? There are a few pages with headlines like:

## GitHub Docs <!-- omit in toc -->

The space between title and comment is not stripped away by the slugger it seems, and the anchor link ends up being #github-docs-. Removing the space would make it harder to read:

## GitHub Docs<!-- omit in toc -->

So if I were to change this, I would keep the space and instead adjust the slugger behavior. To not break existing anchor links, I would make it:

<a name="github-docs-"></a>
## GitHub Docs <!-- omit in toc -->

There are only 11 instances of <!-- omit in toc -->, so not that many <a>s to add, but on the other hand, it's just 11 anchor slugs with trailing hyphens, so not sure if it's worth to look into.

[lucascosti]

Is there a policy how to handle cases where links do get broken? Should one add <a name="former-anchor-slug"></a>? I find examples of that in two files. This seems to be preferred over <a id="..."/> and <a id="..."></a>.

For renaming an entire article, we update all URLs to it in the repo and then set up a redirect for the old URL. However, for in-page section anchors, we generally don't insert manual anchors (like <a name="former-anchor-slug"></a>), but instead do a search of the repo for any internal URLs that use the old anchor and update those to the new one.

On another related note, is it worth to look into avoiding trailing hyphens in anchor slugs? There are a few pages with headlines like:

## GitHub Docs<!-- omit in toc -->

There are only 11 instances of , so not that many s to add, but on the other hand, it's just 11 anchor slugs with trailing hyphens, so not sure if it's worth to look into.

Nice spotting! <!-- omit in toc -->doesn't seem to be used in any site content, and only in the contributing READMEs. So, it's probably not too important for them to have nice anchors.

Feel free to open a PR if you want to update them and remove the space, but I don't think it's too important. If you were to update them, I'd just remove the space and not worry about adding a manual anchor.