Add workflow to create and save versioned references

[gewenyu99]

We want automatically updated, versioned, and persisted references for all SDKs.

See related RFC

This PR does these things:

• Updates script to produce a latest and versioned copy of the references
• The workflow will run on push to master
• The references and only changes in the references folder will be committed to master
• We will pull these in on build on the website later.

See this run on my fork for the workflow

Feel free to bring up suggestions/objections to this approach, but let's keep the discussion in the related RFC for anything that's not repo specific <3

Looking forward to y'all's wisdom and help!

[greptile-apps]

_{5 files reviewed, 5 comments}

_{Edit Code Review Bot Settings | Greptile}

[greptile-apps]

_{3 files reviewed, 2 comments}

_{Edit Code Review Bot Settings | Greptile}

[greptile-apps]

style: Missing newline at end of file.

Suggested change

	file_pattern: references/
	file_pattern: references/

[greptile-apps]

logic: The script writes to ./references/ directory but doesn't ensure it exists first. This could cause a FileNotFoundError if the directory doesn't exist.

Suggested change

	output_file = os.path.join(
	str(OUTPUT_CONFIG["output_dir"]), str(OUTPUT_CONFIG["filename"])
	)
	output_file_latest = os.path.join(
	str(OUTPUT_CONFIG["output_dir"]), str(OUTPUT_CONFIG["filename_latest"])
	)
	output_file = os.path.join(
	str(OUTPUT_CONFIG["output_dir"]), str(OUTPUT_CONFIG["filename"])
	)
	output_file_latest = os.path.join(
	str(OUTPUT_CONFIG["output_dir"]), str(OUTPUT_CONFIG["filename_latest"])
	)
	# Ensure output directory exists
	os.makedirs(str(OUTPUT_CONFIG["output_dir"]), exist_ok=True)

[rafaeelaudibert]

There's a tiny bug here since the workflow is running more often than needed

[rafaeelaudibert]

We don't have this as a requirement in our SDKs, but it'd be better if you set the actions to a specific commit hash rather than to a version like you're doing here. GitHub's ones are fine, but the astral and stefanzweifel ones could be easily compromised/abused. You can look at our main repo to see how that works.

Just a nice to have

[gewenyu99]

Wonderful, I go back to a hash lol. I also agree

I used a hash but greptile was like nono :finger wag:

[rafaeelaudibert]

Not all pushes to master release a new version. Can we add something here to restrict this from running at all times?

Or, maybe something to detect we've already generated docs for that version?

My fear is the following:

• Release V1.0.0
• This workflow generates spec for v1.0.0 and adds in the commit
• Merges a new feature on master but does NOT release it as a new feature
• This workflow generates spec for v1.0.0 and adds in the commit ⚠️⚠️⚠️⚠️⚠️ WRONG

We'd have overwritten the docs for v1.0.0 incorrectly

[gewenyu99]

I think we should still bump latest right (meant to be head of the branch) or do we not bother?

[rafaeelaudibert]

Hmm, I don't think so. We could update something called edge or master, but latest should probably always be the "latest that was actually released".

[gewenyu99]

• I went back to pinning hashes for workflows.
• Only generate on release. No one cares about unreleased stuff anyway :)

[rafaeelaudibert]

I've double checked and we do publish releases here in Github, so lgtm!