|
| 1 | +# PowerMap Static Site – GitHub Actions Versioning & Deployment |
| 2 | + |
| 3 | +This repository is a static HTML site with automated deployment to GitHub Pages and versioned builds managed via Git tags and GitHub Actions. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- Deploys the current site to the `gh-pages` branch automatically on every push to `main` |
| 8 | +- Supports selective deployment using `deploy.json` to control which version is published (e.g., `v2.0.0` or `latest`) |
| 9 | +- Automatically saves versioned builds under `versions/PowerMap_<version>/` when a tag is pushed. (No need to manually copy files into the `versions/` folder) |
| 10 | +- Automatically deletes the corresponding `versions/` folder when a version tag is deleted |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | + |
| 15 | +## Customizing Deployment with `deploy.json` |
| 16 | + |
| 17 | +You can control what version of the site is deployed by editing the `deploy.json` file in the root of the repository. |
| 18 | + |
| 19 | +#### Example |
| 20 | + |
| 21 | +To deploy the latest development files from the root (default behavior): |
| 22 | + |
| 23 | +```json |
| 24 | +{ |
| 25 | + "deploy": "latest" |
| 26 | +} |
| 27 | +``` |
| 28 | +To deploy a specific tagged version, for example v2.0.0, update the file to: |
| 29 | +```json |
| 30 | +{ |
| 31 | + "deploy": "v2.0.0" |
| 32 | +} |
| 33 | +``` |
| 34 | +## GitHub Pages Deployment |
| 35 | + |
| 36 | +The site is deployed automatically via GitHub Actions whenever: |
| 37 | + |
| 38 | +- You push to the `main` branch |
| 39 | +- You create or delete a version tag |
| 40 | +- You update the `deploy.json` file to change which version is deployed |
| 41 | + |
| 42 | +The deployment system reads the `deploy.json` file to determine which version of the site to publish. |
| 43 | + |
| 44 | +- If `"deploy": "latest"` → the root files are deployed (latest dev state) |
| 45 | +- If `"deploy": "vX.X.X"` → the corresponding folder under `versions/PowerMap_vX.X.X/` is deployed |
| 46 | + |
| 47 | +If the specified version doesn't exist, the deployment gracefully falls back to `latest`. |
| 48 | +The deployed site is served from the `gh-pages` branch. |
| 49 | + |
| 50 | +### URL of Deployed Site |
| 51 | +```bash |
| 52 | +https://idataVisualizationLab.github.io/PowerMap/ |
| 53 | +``` |
| 54 | + |
| 55 | + |
| 56 | +## GitHub Actions Workflow |
| 57 | + |
| 58 | +The deployment and versioning behavior is defined in: |
| 59 | +```bash |
| 60 | +.github/workflows/deploy.yml |
| 61 | +``` |
| 62 | +This workflow: |
| 63 | + |
| 64 | +- Creates version folders inside `versions/` on tag push |
| 65 | +- Deletes corresponding version folders on tag deletion |
| 66 | +- Selectively deploys either a specific version or the latest based on `deploy.json` |
| 67 | +- Pushes the selected version to the `gh-pages` branch for public access |
| 68 | + |
| 69 | + |
| 70 | +## Add a New Version (Tag) |
| 71 | +To create a new version (for example, `v2.0.0`), use the following commands: |
| 72 | +```bash |
| 73 | +# Ensure your changes are committed and pushed to main first |
| 74 | +git tag v2.0.0 |
| 75 | +git push origin v2.0.0 |
| 76 | +``` |
| 77 | +> **🚨 Important:** Tags must include the `v` prefix (e.g., `v1.0.0`, `v2.0.0`) to work correctly with the automated workflow. |
| 78 | +
|
| 79 | +#### This will: |
| 80 | + |
| 81 | +- Copy the current project files into versions/PowerMap_v2.0.0/ |
| 82 | +- Commit that folder into the main branch automatically via GitHub Actions |
| 83 | +- Redeploy the site to GitHub Pages (excluding the versions/ folder) |
| 84 | +- You do not need to manually copy files into the versions/ folder — the GitHub workflow handles it. |
| 85 | + |
| 86 | +## Delete a Version |
| 87 | +To delete a previously created version: |
| 88 | +```bash |
| 89 | +git tag -d v2.0.0 |
| 90 | +git push origin :refs/tags/v2.0.0 |
| 91 | +``` |
| 92 | +#### This will: |
| 93 | +- Trigger a GitHub Action that automatically deletes the folder versions/PowerMap_v2.0.0 from the main branch |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | + |
0 commit comments