From 743fa6a27cf5c9dbec676087433e55547561fa12 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 30 May 2026 08:14:58 +0000 Subject: [PATCH 1/5] Initial plan From 02f1ef7438660d1fa8bba482098663486332e81b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 30 May 2026 08:39:14 +0000 Subject: [PATCH 2/5] Document manual website regeneration and deployment workflow --- README.md | 2 ++ development.md | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+) diff --git a/README.md b/README.md index 6bcb98d4..11d82334 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,8 @@ flowchart BT The website will automatically be regenerated and redeployed whenever a new commit is made on—or merged into—the `main` branch of _this_ repository. Regeneration includes pulling content from the remote repositories. The regeneration and redeployment process usually takes about three minutes to complete. +If you need to regenerate/redeploy manually (without making a new commit), see the Deployment section in +[`development.md`](./development.md#deployment). ## The Home section diff --git a/development.md b/development.md index e8bc0eda..b2122e85 100644 --- a/development.md +++ b/development.md @@ -18,6 +18,9 @@ as opposed to the content aspect. * [Runtime section](#runtime-section) * [Workflow docs](#workflow-docs) * [Deployment](#deployment) + * [Automatic deployment](#automatic-deployment) + * [Manual regeneration and deployment (step-by-step)](#manual-regeneration-and-deployment-step-by-step) + * [Workflow details (for GitHub Actions users)](#workflow-details-for-github-actions-users) * [Google Analytics](#google-analytics) @@ -100,6 +103,41 @@ The `.github/workflows` directory contains YAML files that we use to configure G We use GitHub Actions to (a) compile local and remote content into a single website, and to (b) publish that single website to GitHub Pages. +### Automatic deployment + +Website regeneration and deployment happens automatically when a commit is pushed to the `main` branch of this repository. +The workflow that performs this is `.github/workflows/deploy-to-gh-pages.yml` ("Deploy to GitHub Pages"). + +### Manual regeneration and deployment (step-by-step) + +Use this procedure when you need to regenerate and redeploy the website without creating a new commit on `main`. + +1. Open the repository's **Actions** tab: https://github.com/microbiomedata/docs/actions +2. In the left sidebar, click **Deploy to GitHub Pages** +3. Click **Run workflow** +4. In the **Use workflow from** dropdown, select `main` (recommended for production) +5. Click the green **Run workflow** button to start the run +6. Open the new workflow run and monitor the jobs until they complete +7. Confirm both jobs succeeded: + - **Assemble website** + - **Deploy website** +8. Wait ~3 minutes, then verify the live site was refreshed: https://docs.microbiomedata.org + +If the run fails, open the failed job, review the logs, fix the root cause, and run the workflow again. + +### Workflow details (for GitHub Actions users) + +The deployment path is: + +1. `Deploy to GitHub Pages` (`deploy-to-gh-pages.yml`) is triggered (`push` to `main` or `workflow_dispatch`) +2. It calls `Assemble website` (`assemble-website.yml`) +3. `Assemble website` calls these reusable workflows in parallel: + - `compile-home-docs.yml` + - `fetch-and-compile-runtime-docs.yml` + - `fetch-and-compile-workflow-docs.yml` +4. The assembled `github-pages` artifact is link-checked (`check-links.yml`) +5. `actions/deploy-pages` publishes the artifact to GitHub Pages + ## Google Analytics We use Google Analytics to collect and analyze website traffic. You can search the repository for From 72ea091c3caa66df442daa7856950ae8bc6081cd Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sat, 30 May 2026 15:03:36 -0700 Subject: [PATCH 3/5] Simplify and humanize instructions --- README.md | 7 +++++-- development.md | 46 +++++++++++++++------------------------------- 2 files changed, 20 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 11d82334..47dab74e 100644 --- a/README.md +++ b/README.md @@ -103,8 +103,11 @@ flowchart BT The website will automatically be regenerated and redeployed whenever a new commit is made on—or merged into—the `main` branch of _this_ repository. Regeneration includes pulling content from the remote repositories. The regeneration and redeployment process usually takes about three minutes to complete. -If you need to regenerate/redeploy manually (without making a new commit), see the Deployment section in -[`development.md`](./development.md#deployment). + +This repository does _not_ automatically "see" changes made to remote repositories. In other words, +making a change to one of the upstream repositories will not cause the website to be regenerated and +redeployed. To regenerate and redeploy the website in that situation, you can follow the instructions +in the "Deployment" section of the "[Development](./development.md#deployment)" guide. ## The Home section diff --git a/development.md b/development.md index b2122e85..07d5c29b 100644 --- a/development.md +++ b/development.md @@ -19,8 +19,7 @@ as opposed to the content aspect. * [Workflow docs](#workflow-docs) * [Deployment](#deployment) * [Automatic deployment](#automatic-deployment) - * [Manual regeneration and deployment (step-by-step)](#manual-regeneration-and-deployment-step-by-step) - * [Workflow details (for GitHub Actions users)](#workflow-details-for-github-actions-users) + * [Manual deployment](#manual-deployment) * [Google Analytics](#google-analytics) @@ -105,38 +104,23 @@ and to (b) publish that single website to GitHub Pages. ### Automatic deployment -Website regeneration and deployment happens automatically when a commit is pushed to the `main` branch of this repository. -The workflow that performs this is `.github/workflows/deploy-to-gh-pages.yml` ("Deploy to GitHub Pages"). +Whenever a commit is added to the `main` branch of this repository, the website will be regenerated +and redeployed. That happens via the "Deploy to GitHub Pages" GitHub Actions workflow, which is +specified in: `.github/workflows/deploy-to-gh-pages.yml` -### Manual regeneration and deployment (step-by-step) +### Manual deployment -Use this procedure when you need to regenerate and redeploy the website without creating a new commit on `main`. +If you want to regenerate and redeploy the website without adding a commit to the `main` branch of +this repository, you can do so by following the steps below: -1. Open the repository's **Actions** tab: https://github.com/microbiomedata/docs/actions -2. In the left sidebar, click **Deploy to GitHub Pages** -3. Click **Run workflow** -4. In the **Use workflow from** dropdown, select `main` (recommended for production) -5. Click the green **Run workflow** button to start the run -6. Open the new workflow run and monitor the jobs until they complete -7. Confirm both jobs succeeded: - - **Assemble website** - - **Deploy website** -8. Wait ~3 minutes, then verify the live site was refreshed: https://docs.microbiomedata.org - -If the run fails, open the failed job, review the logs, fix the root cause, and run the workflow again. - -### Workflow details (for GitHub Actions users) - -The deployment path is: - -1. `Deploy to GitHub Pages` (`deploy-to-gh-pages.yml`) is triggered (`push` to `main` or `workflow_dispatch`) -2. It calls `Assemble website` (`assemble-website.yml`) -3. `Assemble website` calls these reusable workflows in parallel: - - `compile-home-docs.yml` - - `fetch-and-compile-runtime-docs.yml` - - `fetch-and-compile-workflow-docs.yml` -4. The assembled `github-pages` artifact is link-checked (`check-links.yml`) -5. `actions/deploy-pages` publishes the artifact to GitHub Pages +1. Open the repository's **[Actions](https://github.com/microbiomedata/docs/actions)** tab +2. In the left sidebar, click the GHA workflow names **Deploy to GitHub Pages** +3. In the upper right corner, click the **Run workflow** button +4. In the **Use workflow from** menu that appears, ensure `main` is selected (that's the default) +5. Click the green **Run workflow** button, which will run the GHA workflow +6. Click on the new GHA workflow run and wait for the **Assemble website** job and + the **Deploy website** to finish successfully (i.e. to have a green checkmark) +7. Wait approximately 3 minutes, then visit the website and confirm it shows what you expect ## Google Analytics From 29edd836cbf238d588e64db0f6f93e0ac2b495b3 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sat, 30 May 2026 15:08:45 -0700 Subject: [PATCH 4/5] Fix typos --- development.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/development.md b/development.md index 07d5c29b..ecd83684 100644 --- a/development.md +++ b/development.md @@ -114,12 +114,12 @@ If you want to regenerate and redeploy the website without adding a commit to th this repository, you can do so by following the steps below: 1. Open the repository's **[Actions](https://github.com/microbiomedata/docs/actions)** tab -2. In the left sidebar, click the GHA workflow names **Deploy to GitHub Pages** +2. In the left sidebar, click the GHA workflow named **Deploy to GitHub Pages** 3. In the upper right corner, click the **Run workflow** button 4. In the **Use workflow from** menu that appears, ensure `main` is selected (that's the default) 5. Click the green **Run workflow** button, which will run the GHA workflow -6. Click on the new GHA workflow run and wait for the **Assemble website** job and - the **Deploy website** to finish successfully (i.e. to have a green checkmark) +6. Click on the new GHA workflow run and wait for the **Assemble website** and + **Deploy website** jobs to finish successfully (i.e. to have a green checkmark) 7. Wait approximately 3 minutes, then visit the website and confirm it shows what you expect ## Google Analytics From bc408ce80df164f6a0a5a09979a017f6ab3a1833 Mon Sep 17 00:00:00 2001 From: eecavanna Date: Sat, 30 May 2026 15:16:29 -0700 Subject: [PATCH 5/5] Refrain from triggering GHA workflows when irrelevant files change --- .github/workflows/assemble-website.yml | 10 ++++++++-- .github/workflows/deploy-to-gh-pages.yml | 10 ++++++++-- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/.github/workflows/assemble-website.yml b/.github/workflows/assemble-website.yml index 6baa4513..66091cfd 100644 --- a/.github/workflows/assemble-website.yml +++ b/.github/workflows/assemble-website.yml @@ -4,8 +4,14 @@ name: Assemble website on: # Run this workflow whenever someone opens or adds commits to a PR whose base branch is `main`. - # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request - pull_request: { branches: [ main ] } + # + # References: + # - https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request + # - https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#example-excluding-paths + # + pull_request: + branches: [ main ] + paths-ignore: [ '.gitignore', 'README.md', 'development.md', 'docker-compose.yml' ] # Allow this workflow to be run manually (e.g., via the "Actions" tab on GitHub). # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch workflow_dispatch: { } diff --git a/.github/workflows/deploy-to-gh-pages.yml b/.github/workflows/deploy-to-gh-pages.yml index 0f8bfd97..e6b153fa 100644 --- a/.github/workflows/deploy-to-gh-pages.yml +++ b/.github/workflows/deploy-to-gh-pages.yml @@ -4,8 +4,14 @@ name: Deploy to GitHub Pages on: # Run this workflow whenever someone pushes commits or tags to the `main` branch. - # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push - push: { branches: [ main ] } + # + # Reference: + # - https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push + # - https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#example-excluding-paths + # + push: + branches: [ main ] + paths-ignore: [ '.gitignore', 'README.md', 'development.md', 'docker-compose.yml' ] # Allow this workflow to be run manually (e.g., via the "Actions" tab on GitHub). # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch workflow_dispatch: { }