Improve diff handling for changes to data elements

[jsoref]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

Any article that includes a reusable block.

https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token#generating-a-sha-256-hash-value-for-a-token

What changes are you suggesting?

It'd be really nice if for each changed reusable data file, the tooling would identify one file that consumes it and list the variations of that file.

Conceptually, this can be done by:

1. taking a file path p (data/reusables/actions/workflows/section-triggering-a-workflow-paths.md)
2. stripping data/ from p
3. stripping .md from p (p now has reusables/actions/workflows/section-triggering-a-workflow-paths
4. replacing / with . in p (p now has reusables.actions.workflows.section-triggering-a-workflow-paths)
5. searching for content/ .md files containing {% data +p+ %}
6. arbitrarily picking one (e.g. the first one)

Note that this is the algorithm I applied for the PR referenced below. Except I then had to do the work to find the public and preview versions of the pages which is painful -- whereas the code already can generate both.

Additional information

See #30792 (comment)

[nguyenalex836]

@jsoref Thanks for raising this issue! I'll get this triaged for review ✨

[subatoi]

Thanks for raising an issue! In principle I agree this would be useful, but I'm not sure where this would sit in terms of the overall contributor experience. For example, perhaps we'd add something to the CI, which might print out Markdown filenames that reference specific reusables (per the stepped process you describe in the issue)... but those filenames aren't necessarily a 1:1 map of the actual path under docs.github.com at the moment. Also, I'm not sure how much that hypothetical addition would add to the experience versus doing a search in an IDE, which would be analogous to your fifth step.

Could you help me understand better what sort of thing you'd have in mind, in terms of the actual contributor experience? Perhaps another way of phrasing that: could you expand on what you mean by "tooling"?

[jsoref]

#30792 (comment)

Has a nice table with links to source files and the generated outputs for comparison for before/after. I'm looking for additional extra rows for before/after comparisons for pages impacted by changes to reusable content.

[subatoi]

Got it, thanks! Let me circle back in the new year, when the team in question will be back to full capacity.

[subatoi]

We're going to follow up internally about how we could improve this experience, but for the table solution in particular, it's been pointed out that that could get very large very quickly. Nevertheless it's clear that there's the potential to benefit contributors.

@jsoref as long as you're amenable to it, I'd be inclined to close this issue out—since it's somewhat exceptional by nature in itself, in the context of this repo—and update it again as and when we implement a solution per our internal issue. I do realise that might not be ideal, so I'm happy to discuss it with you further.

[jsoref]

I don't mind. I will note that I created a second ticket that needed this feature this year (after creating this ticket).

Note that as long as you only pull in one sample item for each reusable file instead of all files it shouldn't grow the table much. Bonus points for pulling in different files in cases where two reusable files are used in one.

[subatoi]

One possibility may be that we'd just show one link in the table and then list all of the links in a collapsed section, but I can't guarantee that or a timeframe. Hypothetically, though, would that suit your use case?

[jsoref]

That'd be amazing! And yes, definitely.

Note that I'm here for the long term. I've been waiting years to try to file the spelling PRs for this repository, I'm not bothered by tickets that take time to be resolved.

[subatoi]

OK 😄—in that case, I'll leave this open 👍. And as ever, thank you for all of your help in this repo: we all appreciate it!

[jsoref]

Fwiw, I'd caution you about placing all of the pages into the comment... Probably better to place them in a step summary and link to them from the comment. (See check-spelling-sandbox/apache-arrow@6dafaf5#commitcomment-132855725 for an example.) There's a risk of you running out of bytes if you try to put them all into the comment.

[subatoi]

Thanks for the example! I'll pass that on.

[isaacmbrown]

We're still tracking this internally