docs: Add v1.0.0 snapshot, version documentation, and release-based deployment

.github/workflows/deploy.yml

@@ -1,16 +1,19 @@
 name: Deploy to GitHub Pages
 
 on:
-  push:
-    branches: [main]
-    paths:
-      - "tokens/**"
+  release:
+    types: [published]
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Required to push commits back to main
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v5
+        with:
+          ref: main  # Checkout main branch, not the release tag
+          fetch-depth: 0  # Fetch all history to access previous versions
 
       - name: Setup Node.js
         uses: actions/setup-node@v3
@@ -24,6 +27,43 @@ jobs:
       - name: Validate token list
         run: npm run validate
 
+      - name: Update timestamp
+        run: |
+          # Update timestamp to current UTC time
+          TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+          jq --arg ts "$TIMESTAMP" '.timestamp = $ts' tokens/token-list.json > tokens/token-list.json.tmp
+          mv tokens/token-list.json.tmp tokens/token-list.json
+
+          # Commit timestamp update if changed
+          if ! git diff --quiet tokens/token-list.json; then
+            git config --local user.email "github-actions[bot]@users.noreply.github.com"
+            git config --local user.name "github-actions[bot]"
+            git add tokens/token-list.json
+            git commit -m "chore: Update timestamp for release [skip ci]"
+            git push origin main
+          fi
+
+      - name: Preserve current version as historical snapshot
+        run: |
+          # Get the current version being deployed
+          CURRENT_VERSION=$(jq -r '"\(.version.major).\(.version.minor).\(.version.patch)"' tokens/token-list.json)
+
+          # Check if this version already exists in versions/
+          if [ ! -f "versions/v${CURRENT_VERSION}.json" ]; then
+            mkdir -p versions
+            cp tokens/token-list.json versions/v${CURRENT_VERSION}.json
+            echo "Preserved v${CURRENT_VERSION}.json as historical snapshot"
+
+            # Commit the historical snapshot back to main
+            git config --local user.email "github-actions[bot]@users.noreply.github.com"
+            git config --local user.name "github-actions[bot]"
+            git add versions/v${CURRENT_VERSION}.json
+            git commit -m "chore: Preserve v${CURRENT_VERSION}.json as historical snapshot [skip ci]"
+            git push origin main
+          else
+            echo "v${CURRENT_VERSION}.json already exists in versions/ directory"
+          fi
+
       - name: Create dist directory
         run: |
           mkdir -p dist
@@ -33,13 +73,13 @@ jobs:
           MAJOR=$(jq -r '.version.major' tokens/token-list.json)
           MINOR=$(jq -r '.version.minor' tokens/token-list.json)
 
-          # Copy with full version (e.g., v1.1.0.json)
+          # Copy current version with full version (e.g., v1.1.0.json)
           cp tokens/token-list.json dist/v${VERSION}.json
 
-          # Copy with major.minor version (e.g., v1.1.json)
+          # Copy with major.minor version (e.g., v1.1.json) - updates automatically
           cp tokens/token-list.json dist/v${MAJOR}.${MINOR}.json
 
-          # Copy with major version only (e.g., v1.json)
+          # Copy with major version only (e.g., v1.json) - updates automatically
           cp tokens/token-list.json dist/v${MAJOR}.json
 
           # Copy as latest (always points to newest)
@@ -48,6 +88,12 @@ jobs:
           # Copy base file
           cp tokens/token-list.json dist/token-list.json
 
+          # Copy all historical versions
+          if [ -d "versions" ]; then
+            cp versions/*.json dist/ 2>/dev/null || true
+            echo "Copied historical versions from versions/ directory"
+          fi
+
           echo "Created versioned files: v${VERSION}.json, v${MAJOR}.${MINOR}.json, v${MAJOR}.json, latest.json"
 
       - name: Deploy to GitHub Pages

README.md

@@ -8,17 +8,38 @@ This repository contains a curated list of tokens supported by Request Network p
 
 ## Usage
 
-The token list is available at:
+The token list is available in multiple versioned formats:
+
+### Latest Version (Recommended)
 `https://requestnetwork.github.io/request-token-list/latest.json`
 
-You can fetch the token list directly in your application:
+### Versioned URLs
+Pin to specific versions for stability:
+
+- **Specific patch version**: `https://requestnetwork.github.io/request-token-list/v1.1.0.json`
+- **Latest minor version**: `https://requestnetwork.github.io/request-token-list/v1.1.json` (updates to v1.1.x automatically)
+- **Latest major version**: `https://requestnetwork.github.io/request-token-list/v1.json` (updates to v1.x.x automatically)
+
+### Legacy Path
+For backward compatibility:
+`https://requestnetwork.github.io/request-token-list/token-list.json` (always points to latest)
+
+### Example Usage
 
+Fetch the latest token list:
 ```typescript
 const tokenList = await fetch(
   "https://requestnetwork.github.io/request-token-list/latest.json"
 ).then((res) => res.json());
 ```
 
+Pin to a specific version for production stability:
+```typescript
+const tokenList = await fetch(
+  "https://requestnetwork.github.io/request-token-list/v1.1.0.json"
+).then((res) => res.json());
+```
+
 ## Token List Structure
 
 Each token in the list contains the following information:
@@ -41,9 +62,32 @@ We welcome community contributions! To add a new token to the list:
 
 1. Fork this repository
 2. Add your token information to `tokens/token-list.json`
-3. Make sure your token meets our requirements (see [CONTRIBUTING.md](./CONTRIBUTING.md))
-4. Run tests locally: `npm test`
-5. Create a Pull Request
+3. Bump the version appropriately:
+   - **Patch** (x.x.1): Bug fixes, corrections to existing tokens
+   - **Minor** (x.1.0): New token additions (most common)
+   - **Major** (2.0.0): Breaking changes (e.g., removing tokens, changing schema)
+4. Make sure your token meets our requirements (see [CONTRIBUTING.md](./CONTRIBUTING.md))
+5. Run tests locally: `npm test`
+6. Create a Pull Request
+
+**Note**: The timestamp is automatically updated when the deployment workflow runs after a release is published, marking the deployment time to GitHub Pages.
+
+### 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:
+   - Update the timestamp to the current deployment time
+   - 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](https://github.com/RequestNetwork/request-token-list/actions/workflows/deploy.yml) of this repository.
+
+**Note**: The workflow does not validate that the release tag matches the version in `tokens/token-list.json`. If they don't match, the deployed version will use the version from the JSON file, not the release tag. Always ensure they match to avoid confusion.
 
 ## Development