Document release workflow in edit_workflow.md

[turbomam]

Somehow this didn't make it into the 6.2.2 release... I think Claude and I edited the file in docs/ when it really should have gone in src/docs. docs/ is gitignored.

Summary

• Fills in the empty # Releases section in src/docs/edit_workflow.md
• Documents the automated GitHub Actions release workflow
• Includes pre-merge checklist, post-merge publishing steps, and versioning guidance

Details

This PR addresses feedback from @mslarae13 on PR #1088 regarding documenting the release process.

The new documentation covers:

• How to trigger the release workflow (GitHub Actions)
• What the workflow does automatically
• Pre-merge checklist for reviewers
• Post-merge steps for publishing releases on GitHub
• Release publishing permissions
• Semantic versioning guidance

Closes #120

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://GenomicsStandardsConsortium.github.io/mixs/pr-preview/pr-1090/
Built to branch gh-pages at 2026-03-10 22:35 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[turbomam]

Suggested Addition: Tag Naming Warning

Based on issues encountered during the v6.2.3 release (see #1104), this documentation should include a warning about tag naming conventions.

Suggested text to add after the parameters section:

Important: The diff_old and diff_new fields must be valid git references. Tag naming changed at v6.2.0:

• v6.2.0 and later: v6.2.0, v6.2.2, v6.2.3 (with v prefix)
• Earlier releases: mixs6.0.0, mixs6.1.0, mixs6.1.1 (with mixs prefix)

Check the exact tag name at Releases before running the workflow.

This would help prevent the confusion that occurred when 6.2.2 was entered instead of v6.2.2.

[turbomam]

Rebase & cross-reference note (2026-03-10)

This PR was rebased onto current main along with #1115, #1110, and #1130.

Dependency: #1115 should merge before this PR. That PR changes the release workflow parameters to a unified mixs-legacy-diff tool and replaces the diff result files. After #1115 merges, this PR will need updates to reflect the new workflow parameter format.

• Add curated schema diff documentation for v6.0.0 to main #1110 (schema diff docs) also depends on Unified mixs-legacy-diff tool: v4+ schema comparison with CI tests #1115.
• Test MIxS build against linkml main + TSV list normalization demo #1130 (LinkML main compat test) is independent.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The text says the workflow "will" run the full build and test suite, but the workflow has a skip_tests input that runs make ... all without test when set. Please reword this section to describe the conditional behavior (tests run unless skip_tests is true).

Suggested change

	- `skip_tests`: Optional, for faster iteration during development
	4. Click **Run workflow**
	The workflow will:
	- Bump version numbers in `pyproject.toml`, `CITATION.cff`, `.zenodo.json`, and `release/README.md`
	- Run the full build and test suite
	- `skip_tests`: Optional, for faster iteration during development; when set, skips running the test suite
	4. Click **Run workflow**
	The workflow will:
	- Bump version numbers in `pyproject.toml`, `CITATION.cff`, `.zenodo.json`, and `release/README.md`
	- Run the full build and, unless `skip_tests` is true, the test suite

[turbomam]

Valid — good catch. The doc says "Run the full build and test suite" unconditionally, but the workflow (lines 108–114) has two branches: make install clean all test when skip_tests is false, and make install clean all when true. The text here should reflect that the test suite is conditional.

Will update this line to say something like "Run the full build and, unless skip_tests is true, the test suite" as you suggest.

[Copilot]

This doc points reviewers to assets/diff_results/schema_comparison_results.yaml, but the workflow intentionally does not fail if diff generation errors (|| echo ...), which can leave this file missing or incomplete. Consider adding a note that reviewers should also check the Actions logs if the diff file isn't present/looks incomplete.

Suggested change

	- [ ] Review schema diff for unexpected changes (see `assets/diff_results/schema_comparison_results.yaml`)
	- [ ] Review schema diff for unexpected changes (see `assets/diff_results/schema_comparison_results.yaml`). If this file is missing or looks incomplete, open the corresponding workflow run in GitHub Actions and review the logs for any schema diff generation errors.

[turbomam]

Valid. The workflow uses || echo "Diff generation encountered issues - check logs" (line 129 of the workflow YAML), which means the diff step will silently succeed even if the actual diff tool errors out. The output file could end up missing or incomplete with no signal in the PR itself.

Adding a reviewer-facing note as you suggest is a good low-cost fix. We could also consider failing the workflow on diff errors and making the || echo fallback opt-in, but that's a separate discussion — the doc fix is worth doing either way.

[Copilot]

Listing specific GitHub usernames/roles for release publishing permissions is likely to become stale as repo permissions change. Consider referencing a GitHub team (or a link/instruction to check the repository "Manage access" settings) instead of hard-coding individual accounts in this doc.

Suggested change

	Users with release publishing permission:
	- **Admins**: @lschriml, @only1chunts
	- **Maintain**: @sujaypatil96, @turbomam
	Release publishing is restricted to users with **Admin** or **Maintain** access on the repository.
	To see who currently has these permissions, open the GitHub repository and go to **Settings → Collaborators and teams** (or **Settings → Manage access**).

[turbomam]

Valid. Hard-coding GitHub usernames will go stale as repo membership changes. Pointing to Settings > Collaborators and teams (or referencing a GitHub team) is more maintainable.

Will replace the username list with a reference to the repo's access settings, similar to your suggestion.