docs: Add v1.0.0 snapshot, version documentation, and release-based deployment #13
Conversation
WalkthroughUpdated README to add versioned token-list usage, examples, contribution and publishing guidance. Updated GitHub Actions deploy workflow to trigger on releases, grant repo write permissions, record a timestamp, preserve historical Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Release as "Release Published"
participant GH as "GitHub Actions"
participant Repo as "Repository"
participant FS as "Workspace (tokens/, versions/, dist/)"
rect rgba(198,239,206,0.18)
Note over Release,GH: release: published triggers deploy workflow
Release->>GH: trigger workflow
GH->>Repo: checkout (v5, main, fetch-depth: 0)
end
rect rgba(135,206,250,0.10)
Note over GH,FS: Update timestamp & preserve snapshot
GH->>FS: write UTC timestamp into `tokens/token-list.json` (commit if changed)
GH->>FS: read version from `tokens/token-list.json`
alt snapshot for version missing
GH->>FS: copy -> `versions/vX.Y.Z.json`
GH->>Repo: commit & push snapshot (skip CI)
else snapshot exists
GH-->>FS: noop
end
end
rect rgba(255,243,205,0.12)
Note over GH,FS: Build dist including historical versions (conditional)
GH->>FS: if `versions/` exists
alt exists
GH->>FS: copy `versions/*` -> `dist/`
else not exists
GH-->>FS: skip copy
end
end
rect rgba(220,220,220,0.06)
Note over GH,Repo: continue remaining build and publication steps
GH->>Repo: generate versioned artifacts (`vX.Y.Z.json`, `vX.Y.json`, `vX.json`, `latest.json`) and publish
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Pull Request Overview
This PR enhances the README documentation to describe the new versioned URL scheme for accessing the token list, making it easier for consumers to choose between automatic updates and stability.
- Added documentation for multiple versioning strategies (latest, major, minor, patch)
- Included version history tracking with release notes
- Provided examples for both latest and pinned version usage
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
MantisClone
force-pushed
the
docs/add-version-1.0.0-and-readme
branch
from
9888abb to
f3cfe5f
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
README.md (1)
27-29: Version history serves its purpose as a starting point.The entries document v1.0.0 and v1.1.0, aligning with PR objectives. While entries are minimal, they are adequate for this release. As the project matures, consider adding release dates and links to detailed changelogs per version for transparency.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🔇 Additional comments (2)
README.md (2)
11-25: Documentation is clear and well-organized.The versioning section effectively communicates the available URL patterns and their behavior. The distinction between patch-specific (v1.1.0), latest minor (v1.1), and latest major (v1) pinning is intuitive and helpful for consumers with different stability/freshness trade-offs.
Verification request: Confirm that all documented URL patterns (latest.json, v1.1.0.json, v1.1.json, v1.json, and token-list.json) are actually deployed and accessible. If any pattern is not yet deployed, the documentation should be updated to reflect actual availability.
31-45: Examples are practical and accurate.Both code snippets correctly demonstrate the documented URL patterns and use standard fetch patterns familiar to TypeScript consumers. Clear comments distinguish the latest vs. pinned version use cases.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
.github/workflows/deploy.yml (1)
36-57: Update the final echo to reflect all deployed versions.Line 57's echo message doesn't account for the historical versions copied in the conditional block. Consider updating it for transparency and debugging clarity.
- echo "Created versioned files: v${VERSION}.json, v${MAJOR}.${MINOR}.json, v${MAJOR}.json, latest.json" + if [ -d "versions" ]; then + echo "Created versioned files: v${VERSION}.json, v${MAJOR}.${MINOR}.json, v${MAJOR}.json, latest.json, and copied historical versions" + else + echo "Created versioned files: v${VERSION}.json, v${MAJOR}.${MINOR}.json, v${MAJOR}.json, latest.json" + fiAlternatively, simplify to a single message:
- echo "Created versioned files: v${VERSION}.json, v${MAJOR}.${MINOR}.json, v${MAJOR}.json, latest.json" + echo "Deployment prepared with versioned files in dist/"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/workflows/deploy.yml(2 hunks)README.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- README.md
🔇 Additional comments (1)
.github/workflows/deploy.yml (1)
51-55: Update workflow trigger to include historical version files.The conditional block correctly copies historical versions from
versions/when the directory exists, but the workflow trigger (paths: ["tokens/**"]) won't fire when files are added toversions/. This creates a gap: if new historical versions are added, they won't be deployed without manual workflow dispatch or committing to thetokens/directory.Verify whether this is intentional (one-time setup for v1.0.0.json) or if the workflow trigger should be updated to include
versions/**.If ongoing version management is anticipated, update the workflow trigger:
on: push: branches: [main] paths: - - "tokens/**" + - "tokens/**" + - "versions/**"
…based deployment - Add versions/v1.0.0.json as historical snapshot extracted from commit bf10c55 - Document version URL patterns in README (v1.1.0.json, v1.1.json, v1.json, latest.json) - Add version history and usage examples - Update deploy workflow to trigger on GitHub Release instead of main branch pushes - Automate preservation of historical versions when releasing - Document release process for maintainers in README
MantisClone
force-pushed
the
docs/add-version-1.0.0-and-readme
branch
from
f3cfe5f to
3bc6844
Compare
MantisClone
changed the title
…rvation - Add contents: write permission to allow workflow to push to main - Checkout main branch instead of release tag to enable proper git push - Ensures historical version snapshots can be committed automatically
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
README.md (2)
65-73: Clarify timestamp field name and expected format.Line 69 instructs contributors to "Update the timestamp to the current date," but doesn't specify:
- Which field in
tokens/token-list.jsonshould be updated (e.g.,timestamp,updatedAt,version_metadata.timestamp?)- The required date/time format (ISO 8601, Unix epoch, etc.)
- Whether the timestamp updates automatically via CI or requires manual entry
This ambiguity could lead to inconsistent or missing timestamp updates in contributions.
Update the instruction to specify the exact field and format:
-4. Update the timestamp to the current date +4. Update the `timestamp` field in `tokens/token-list.json` to the current UTC date in ISO 8601 format (e.g., `2025-11-04T12:00:00Z`)
74-82: Provide more detail on the automatic deployment mechanism.The publishing workflow section is clear on the high-level steps (create release, deployment is automatic), but readers may wonder:
- Does the workflow validate that the release tag matches the version in
tokens/token-list.json?- What happens if there's a mismatch?
- How long does deployment typically take?
- Where can maintainers monitor deployment progress?
Consider expanding this section with a brief troubleshooting or validation checklist to reduce confusion.
Optionally enhance the publishing section with:
### Publishing a New Version After merging changes to `main`: 1. Create a GitHub Release with a tag matching the version in `tokens/token-list.json` (e.g., `v1.2.0`) + - The tag must use the format `v<MAJOR>.<MINOR>.<PATCH>` (e.g., `v1.2.0`) + - Ensure the release tag matches the version in your token list exactly 2. The deployment workflow will automatically: - Preserve the new version as a historical snapshot in `versions/` - Deploy all versioned files to GitHub Pages - Make the new version available at all URL patterns + + Monitor deployment progress in the [Actions tab](../../actions/workflows/deploy.yml) of this repository.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/workflows/deploy.yml(4 hunks)README.md(2 hunks)
🧰 Additional context used
🪛 actionlint (1.7.8)
.github/workflows/deploy.yml
11-11: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
🔇 Additional comments (4)
.github/workflows/deploy.yml (1)
72-76: Clean handling of historical version copying.The logic correctly handles the case where the
versions/directory may not exist, and the error suppression with|| trueis appropriate here.README.md (3)
11-25: Clarify the versioning URL pattern mechanism and support.The README documents URL patterns (
v1.1.json,v1.json) that automatically update to the latest minor/major version, but doesn't explain how this is implemented. Without clarity on whether these are generated files, routing rules, or GitHub Pages redirects, readers cannot reliably depend on these patterns.Additionally, the PR objectives mention adding
v1.0.0.jsonas a historical snapshot, but it's not referenced in the documentation. Should the README list available versions or document how to discover them?Please clarify the versioning mechanism by describing how:
- The deployment workflow creates/maintains
v1.1.jsonandv1.jsonfiles- These files are kept in sync with the latest patch/minor versions respectively
- Whether historical versions like
v1.0.0.jsonare discoverable/documentedYou may want to add a brief note explaining that versioned files are automatically managed by the deployment workflow. If the deploy.yml changes contain specific logic for this, consider cross-referencing it in the README (e.g., "See
.github/workflows/deploy.ymlfor version management details").
27-41: LGTM — Examples are clear and practical.The TypeScript examples effectively demonstrate both the latest and pinned version patterns, making it easy for consumers to adopt the appropriate URL for their use case (auto-updating vs. stable).
65-68: Version semantics are well documented.The patch/minor/major guidance is clear and aligns with semantic versioning conventions. The note that "New token additions (most common)" is pragmatic and helps contributors make appropriate versioning decisions.
- Add workflow step to update timestamp to current UTC time when releasing - Remove manual timestamp update requirement from README - Timestamp automatically set before version snapshot is preserved - Ensures consistent and accurate release timestamps
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
README.md (1)
73-73: Clarify the timestamp update behavior.The note on line 73 states "The timestamp is automatically updated by the deployment workflow when a release is published." This could be misleading—the timestamp in the release tag (at merge time) differs from the timestamp in the preserved snapshot (at deployment time). Consider clarifying: "The timestamp is automatically updated when the deployment workflow runs after a release is published, marking the deployment time to GitHub Pages."
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/workflows/deploy.yml(4 hunks)README.md(2 hunks)
🔇 Additional comments (7)
.github/workflows/deploy.yml (4)
10-16: Excellent fix for the detached HEAD issue from previous review.Checking out the
mainbranch (line 15) instead of the release tag ensures that subsequentgit commitandgit pushoperations target the main branch correctly. The permissions grant (line 11) andfetch-depth: 0(line 16) properly support the workflow's needs.
30-44: Verify that timestamp update timing aligns with intent.The timestamp is updated during workflow execution (deployment time) rather than at release creation time. This means the release tag v1.2.0 will have a different timestamp than the preserved snapshot
versions/v1.2.0.json. Confirm this is intentional—if the goal is to preserve the exact state released, the timestamp should be skipped or the snapshot should be created before the timestamp update.Also consider: If two releases are published in quick succession, the sequential
git pushoperations on lines 43 and 62 could potentially race or conflict. Evaluate whether a single batch commit-and-push at the end would be safer.
46-65: Multiple sequential git push operations may create race conditions or require handling.The workflow has two separate
git pushoperations at lines 43 and 62. If another commit is pushed to main between these two pushes (unlikely but possible in high-volume scenarios), the second push could fail. Consider:
- Combining both commits into a single batch before pushing (timestamp + snapshot preservation)
- Adding error handling or retry logic
- Using
git pull origin mainbefore the second push to refreshAdditionally, there is no error handling if
jqextraction on line 49 fails—the workflow will continue and may preserve an incomplete or invalid snapshot.
91-95: Solid implementation of historical version distribution.The conditional copy of historical versions to
dist/ensures all preserved versions are deployed to GitHub Pages. The error suppression with|| trueis appropriate for the case whereversions/is empty. This correctly implements the multi-version availability described in the PR objectives.README.md (3)
9-41: Clear and comprehensive versioning documentation.The Usage section effectively communicates the available URL patterns and their behaviors. The examples demonstrate both latest-version (auto-updating) and pinned-version (stable) consumption patterns, which aligns with the deployment strategy. The URL patterns documented (v1.1.0.json, v1.1.json, v1.json, latest.json) match the outputs created in the deploy workflow.
75-83: Clear release process documentation.The Publishing a New Version section provides actionable steps for maintainers and correctly documents the automated workflow behavior. The instruction to tag releases with matching version numbers (e.g.,
v1.2.0) is explicit and aligned with the deployment workflow's version extraction logic.
85-112: Development and Validation sections look good.Clear prerequisites, installation, and testing guidance. The Validation section appropriately documents what the CI/CD pipeline checks.
- Explain that timestamp reflects deployment time to GitHub Pages - Distinguish between merge time and deployment workflow execution time
- Add tag format requirements (v<MAJOR>.<MINOR>.<PATCH>) - Clarify that workflow updates timestamp during deployment - Add link to Actions tab for monitoring deployment progress - Document mismatch behavior between release tag and JSON version - Provide complete deployment workflow steps
Problem
After implementing versioned deployment in PR #12, we're missing:
Proposed Solution
versions/v1.0.0.jsoncontaining the token list from before PR feat: Add GHO, USDS (Sky), and MetaMask USD tokens #12 mergeImplementation Details
Automated Timestamp Updates
Version Preservation
versions/directoryversions/*.jsonto GitHub PagesDeployment Trigger
release.publishedeventVersion URLs
All versions automatically deployed to GitHub Pages:
v1.1.0.json- Frozen specific versionv1.1.json- Auto-updates to latest 1.1.xv1.json- Auto-updates to latest 1.x.xlatest.json- Always newest versiontoken-list.json- Legacy path (points to latest)Maintainer Workflow
v1.2.0)Documentation Enhancements
v<MAJOR>.<MINOR>.<PATCH>)Considerations
Summary by CodeRabbit
Documentation
Chores