From 8d26b25476e974a76c0a67bca823c7a5d8fe3385 Mon Sep 17 00:00:00 2001 From: acaptutorials Date: Fri, 29 Aug 2025 19:51:54 +0800 Subject: [PATCH 1/6] chore: rename development yml to docker-compose.yml --- .github/workflows/deploy-prod.yml | 4 ++-- .github/workflows/pull-images.yml | 2 +- README.md | 14 +++++++------- docker-compose.dev.yml => docker-compose.yml | 0 4 files changed, 10 insertions(+), 10 deletions(-) rename docker-compose.dev.yml => docker-compose.yml (100%) diff --git a/.github/workflows/deploy-prod.yml b/.github/workflows/deploy-prod.yml index 96547653..25125c6f 100644 --- a/.github/workflows/deploy-prod.yml +++ b/.github/workflows/deploy-prod.yml @@ -90,7 +90,7 @@ jobs: run: cp docs/.env.example docs/.env - name: Build Image - run: docker compose -f docker-compose.dev.yml build + run: docker compose build - name: Push Image to Docker Hub - run: docker compose -f docker-compose.dev.yml push + run: docker compose push diff --git a/.github/workflows/pull-images.yml b/.github/workflows/pull-images.yml index c70fb5bc..52d13d31 100644 --- a/.github/workflows/pull-images.yml +++ b/.github/workflows/pull-images.yml @@ -26,4 +26,4 @@ jobs: run: cp docs/.env.example docs/.env - name: Pull Development Image - run: docker compose -f docker-compose.dev.yml pull + run: docker compose pull diff --git a/README.md b/README.md index 97126df1..b25f2450 100644 --- a/README.md +++ b/README.md @@ -70,13 +70,13 @@ The app depends these libraries and frameworks. 2. (Optional) Run the app for local development using Docker. Navigate to the project's root directory then run:
``` # 2.1. Build the client and server containers for localhost development. - docker compose -f docker-compose.dev.yml build + docker compose build # 2.2. Create and start the development client and server containers - docker compose -f docker-compose.dev.yml up + docker compose up # 2.3. Stop and remove the development containers, networks, images and volumes - docker compose -f docker-compose.dev.yml down + docker compose down ``` 3. Add or edit MDX files in the `/pages` directory, or add React components in the `/components` directory. @@ -111,13 +111,13 @@ https://hub.docker.com/r/acaptutorials/acaptutorials.github.io 1. Pull the development Docker image from Docker Hub using one of the options.
- `docker pull acaptutorials/acaptutorials.github.io:latest` - - `docker compose -f docker-compose.dev.yml pull` (using Docker compose from the root project directory) + - `docker compose pull` (using Docker compose from the root project directory) 2. Navigate to the project directory using the command line. Create a `.env` file inside the **/docs** directory with reference to the `.env.example` file. - See [Usage](#usage) - **step # 2** for more information. 3. Run the development Docker image.
-`docker compose -f docker-compose.dev.yml up` +`docker compose up` 4. (Optional) Run the development Docker image (from other directories).
`docker run -it --rm -p 3000:3000 acaptutorials/acaptutorials.github.io:latest` @@ -125,13 +125,13 @@ https://hub.docker.com/r/acaptutorials/acaptutorials.github.io ### Build the Development Docker Image 1. Build the development Docker image on your machine.
-`docker compose -f docker-compose.dev.yml build` +`docker compose build` 2. Navigate to the project directory using the command line. Create a `.env` file inside the **/docs** directory with reference to the `.env.example` file. - See [Usage](#usage) - **step # 2** for more information. 3. Run the development Docker image.
-`docker compose -f docker-compose.dev.yml up` +`docker compose up` ## Usage with GitHub Actions diff --git a/docker-compose.dev.yml b/docker-compose.yml similarity index 100% rename from docker-compose.dev.yml rename to docker-compose.yml From 81be5e996178481e732d72e1e6d3efaeafd12789 Mon Sep 17 00:00:00 2001 From: acaptutorials Date: Sat, 30 Aug 2025 01:38:48 +0800 Subject: [PATCH 2/6] docs: note discontinuation of pagasa 10-day excel files in announcements, #99 --- README.md | 1 + docs/pages/announcements.mdx | 6 + docs/pages/announcements/_meta.json | 4 + .../announcements/pagasa-10day-excel.mdx | 121 ++++++++++++++++++ .../articles/provinces-municipalities.mdx | 4 + .../weather-forecasts/tenday-forecast.mdx | 4 + 6 files changed, 140 insertions(+) create mode 100644 docs/pages/announcements/pagasa-10day-excel.mdx diff --git a/README.md b/README.md index b25f2450..f1707c65 100644 --- a/README.md +++ b/README.md @@ -155,6 +155,7 @@ https://hub.docker.com/r/acaptutorials/acaptutorials.github.io | --- | --- | | DOCKERHUB_USERNAME | Docker Hub username | | DOCKERHUB_TOKEN | Deploy token for the Docker Hub account | +| FIREBASE_TOKEN | Firebase CI token for deployment to Firebase Hosting | #### GitHub Variables diff --git a/docs/pages/announcements.mdx b/docs/pages/announcements.mdx index ec1351c5..b971df66 100644 --- a/docs/pages/announcements.mdx +++ b/docs/pages/announcements.mdx @@ -9,3 +9,9 @@ import { Cards, Image } from 'nextra/components' <>![Documentation theme](/assets/docs-theme.png) + + + + <>![Documentation theme](/assets/docs-theme.png) + + \ No newline at end of file diff --git a/docs/pages/announcements/_meta.json b/docs/pages/announcements/_meta.json index dd0947cb..1d6704a7 100644 --- a/docs/pages/announcements/_meta.json +++ b/docs/pages/announcements/_meta.json @@ -2,5 +2,9 @@ "firebase-storage-2024": { "title": "Firebase Storage Pricing Plan Changes (2024)", "type": "page" + }, + "pagasa-10day-excel": { + "title": "PAGASA 10-Day Excel Files Discontinued", + "type": "page" } } diff --git a/docs/pages/announcements/pagasa-10day-excel.mdx b/docs/pages/announcements/pagasa-10day-excel.mdx new file mode 100644 index 00000000..0e1511a4 --- /dev/null +++ b/docs/pages/announcements/pagasa-10day-excel.mdx @@ -0,0 +1,121 @@ +import { useEffect, useState, useMemo } from 'react' +import { useTheme } from 'next-themes' +import { Callout } from 'nextra/components' + +export function FAQBox({ title, children, open = false, color = '' }) { + // Copied from /articles/provinces-municipalities.mdx + const [isClient, setIsClient] = useState(false) + const { theme, resolvedTheme } = useTheme() + + useEffect(() => { + setIsClient(true) + }, []) + + const detailsBgStyle = useMemo(() => { + const bg = resolvedTheme === 'dark' + ? 'bg-neutral-800' + : 'bg-neutral-50' + + return `last-of-type:mb-0 rounded-lg ${bg} p-2 mt-4` + }, [resolvedTheme]) + + return !isClient + ?
...
+ : ( +
+ + {title} + +
{children}
+
+ ) +} + +# PAGASA 10-Day Excel Files Discontinued + +**Effective August 31, 2025** + +## What's Changing + + +Starting **August 31, 2025**, PAGASA will no longer provide its **10-Day Weather Forecast in Excel format**. +Instead, all forecasts will be delivered through the new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) launched in **July 2025**. +This means any ACAP process, report, or system that currently relies on downloading Excel files will cease to function unless updated to use the API. + +_Note: PAGASA has not announced plans to archive past Excel files._ + + +
+Click to view the attached screenshot of PAGASA's announcement for more information. +![PAGASA 10-Day Excel files discontinuation announcement](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FNOZHqk2E8F8RoVvZuVVv_file?alt=media&token=88bd0b49-b7ee-45f8-843e-11bd0b9dcfe6) +
+ +## FAQs + +The following FAQs explain who will be affected, why this change is happening, and how projects should prepare. + + +Projects that use the **PAGASA 10-Day Weather Forecast Excel files**. + +It includes **components in acap-v2** ([ACAP 2.0](/changelog/#version-2-acap-20)) and **climate-services-webportal-v1** ([ACAP 1.0](/changelog/#version-1-acap-10)), plus any forks, scripts, or automated tasks fetching Excel-based forecasts: + +1. [Provinces and municipalities listing](/articles/provinces-municipalities/) +2. [10-Day Weather Forecast data](/post-installation/weather-forecasts/tenday-forecast/) +3. _([ACAP-RCMAS REST APIs](/post-installation/acap-rcmas-api) - if these APIs are activated)_ +4. Automated scripts/workflows + + +After **August 31, 2025**, all workflows relying on Excel files will fail unless updated to use the API. + + + + + +PAGASA is modernizing data sharing by moving from Excel files to REST APIs, reducing brittle manual steps, and enabling more robust integrations. + +The new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) (launched July 2025) covers both **10-Day** and **Seasonal weather forecasts**. + + +It is not yet known whether PAGASA will also discontinue the **Seasonal Weather Forecast Excel files**. + + + + + + +There are currently no news or directives for syncing the parent **acap-v2** code repository to the **PAGASA TenDay API**. Projects using it as base template (including ACAP Bicol) are advised to sync their ACAPs to the API. + + +Here are the recommended migration steps for syncing ACAP to the PAGASA TenDay API. However, feel free to adjust and customize as deemed necessary. + +1. Review the [PAGASA TenDay API documentation](https://tenday.pagasa.dost.gov.ph/docs). +2. Request an **API key** from PAGASA. +3. **Regional location data:** Build the provinces and municipalities list from the PAGASA TenDay API, possibly from its **Validation - Location** endpoint at `"https://tenday.pagasa.dost.gov.ph/api/v1/location"`. +4. **Data source:** Replace the **10-Day weather forecast data** Excel fetch/parse logic with **TenDay API REST responses**. +5. Update scripts β€” Excel downloads will stop after August 31, 2025. + + +**Tip:** ACAP (1.0 until version 2.0 - 2.1) processes its **provinces and municipalities list** and **10-day weather forecast data** using the `"npm run cron:tenday"` NPM script, under the `"/server/src/scripts/cron/update_tenday_weather"` folder. + +Inspect and customize scripts in this folder to sync with the PAGASA TenDay API. + +Revisiting ACAP's architecture diagrams in the root `README` and `"/server/src/scripts/generate-docs/templates/img-acap.png"` may also help. + + + + + +Visit these references to learn more about the changes. + +- [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) +- [10-Day Weather Forecast](/post-installation/weather-forecasts/tenday-forecast/) +- [Provinces and Municipalities](/articles/provinces-municipalities) +- [ACAP-RCMAS REST APIs](/post-installation/acap-rcmas-api) + + +--- + +*Disclaimer: This documentation update does not imply ongoing involvement with the project.* \ No newline at end of file diff --git a/docs/pages/articles/provinces-municipalities.mdx b/docs/pages/articles/provinces-municipalities.mdx index ace3db41..bc1f2d22 100644 --- a/docs/pages/articles/provinces-municipalities.mdx +++ b/docs/pages/articles/provinces-municipalities.mdx @@ -39,6 +39,10 @@ export function FAQBox({ title, children, open = false }) { ACAP uses a combination of the [PAGASA 10-day weather forecast Excel files](https://www.pagasa.dost.gov.ph/climate/climate-prediction/10-day-climate-forecast) and the [PAGASA Seasonal Forecast- Forecast Rainfall Analysis Table](https://www.pagasa.dost.gov.ph/climate/climate-prediction/seasonal-forecast) as a data source for its region, provinces, and municipalities list. + +Starting **August 31, 2025**, PAGASA will no longer provide the **10-Day Excel files**. Check the [Announcements](/announcements/pagasa-10day-excel) section for more information. + + ## FAQs diff --git a/docs/pages/post-installation/weather-forecasts/tenday-forecast.mdx b/docs/pages/post-installation/weather-forecasts/tenday-forecast.mdx index 7ecbf10e..df53d210 100644 --- a/docs/pages/post-installation/weather-forecasts/tenday-forecast.mdx +++ b/docs/pages/post-installation/weather-forecasts/tenday-forecast.mdx @@ -4,6 +4,10 @@ import { Callout, Steps } from 'nextra/components' ![pagasa-10day](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2Flct0mjyQ7jZqOvL9R9Bt_thumbnail?alt=media&token=73f8d105-ccfa-4654-bed3-5863db824bba) + +Starting **August 31, 2025**, PAGASA will no longer provide the **10-Day Excel files**. Check the [Announcements](/announcements/pagasa-10day-excel) section for more information. + + ## Introduction ACAP sources its 10-day weather forecast data from PAGASA's public 10-day weather forecast data (available as Excel files from day 1 - day 10) in their **10-Day Climate Forecast** web page at https://www.pagasa.dost.gov.ph/climate/climate-prediction/10-day-climate-forecast. From e666e7c451dd4d76ed0a297198c58ed324e6a1f0 Mon Sep 17 00:00:00 2001 From: acaptutorials Date: Sat, 30 Aug 2025 03:59:45 +0800 Subject: [PATCH 3/6] docs: add notes about git flow, branching and ci/cd --- docs/pages/articles/deployment.mdx | 46 ++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/pages/articles/deployment.mdx b/docs/pages/articles/deployment.mdx index 32c7bc1a..773c1a63 100644 --- a/docs/pages/articles/deployment.mdx +++ b/docs/pages/articles/deployment.mdx @@ -10,6 +10,52 @@ These videos created for ACAP's initial release (ACAP 1.0) back in **2023** shou Follow the steps in the **Render Initial Blueprint Instance** section to sync its Render deployment methods with the ACAP 2.0 updates. +## Git Flow + +CI/CD using GitHub Actions deploy code updates to the **development** or **production** environments following this [simplified version of Git Flow](https://youtu.be/cV-9KszXEyw?feature=shared&t=845). + +acap-git-flow + + +**(Optional)** Before proceeding, create a GitHub Issue describing the new feature, bug fix or task that you'll develop. This tracks the details of the incoming updates. + + + +### Create a feature branch + +- Create a **feature branch** branching out from the **dev branch** + + > If a GitHub Issue describes this feature, name the branch with the GitHub Issue number eg., `feat/acaptutorials-12` (Issue #12) + + ```sh + git checkout dev + git checkout -b feat/acaptutorials-12 + + # Using other branch names + # git checkout -b awesome-update + ``` + +- This isolates new work (feature, bug fix, or task) so it doesn't destabilize the shared development branch. + +### Merge the feature branch back to dev + +- Once the feature is complete and reviewed via a **Pull Request (PR)**, it's merged back into **dev**. +- Approving a PR to the dev branch (or pushing updates directly to the dev branch) triggers a deployment to the **development** (Firebase Hosting, Render and, [Vercel](/articles/deployment-vercel) (if available)) environment. +- It allows testing the feature with other in-progress features in an integrated (development) environment. +- Delete the feature branch afterward to keep the repository clean. + +### Promote dev to master + +- When the **dev branch** has accumulated stable, tested features, create a Pull Request (PR) to **master** +- The master branch always reflects the code that's safe to release to production. + +### Tag a release + +- Tag and version a release from the **master branch** (e.g., v1.0.0). +- This creates an immutable snapshot of the code that corresponds to a specific release. +- It also triggers a deployment to the **production** (GitHub Pages, Render and, [Vercel](/articles/deployment-vercel) (if available)) environment. + + ## Render Initial Blueprint Instance From 35cb71e8eb2b3de2339d41ef68f9730d0caee3c9 Mon Sep 17 00:00:00 2001 From: acaptutorials Date: Sat, 30 Aug 2025 04:22:59 +0800 Subject: [PATCH 4/6] chore: create front page for articles --- .../announcements/pagasa-10day-excel.mdx | 240 +++++++++--------- docs/pages/articles.mdx | 16 ++ 2 files changed, 136 insertions(+), 120 deletions(-) create mode 100644 docs/pages/articles.mdx diff --git a/docs/pages/announcements/pagasa-10day-excel.mdx b/docs/pages/announcements/pagasa-10day-excel.mdx index 0e1511a4..f5431230 100644 --- a/docs/pages/announcements/pagasa-10day-excel.mdx +++ b/docs/pages/announcements/pagasa-10day-excel.mdx @@ -1,121 +1,121 @@ -import { useEffect, useState, useMemo } from 'react' -import { useTheme } from 'next-themes' -import { Callout } from 'nextra/components' - -export function FAQBox({ title, children, open = false, color = '' }) { - // Copied from /articles/provinces-municipalities.mdx - const [isClient, setIsClient] = useState(false) - const { theme, resolvedTheme } = useTheme() - - useEffect(() => { - setIsClient(true) - }, []) - - const detailsBgStyle = useMemo(() => { - const bg = resolvedTheme === 'dark' - ? 'bg-neutral-800' - : 'bg-neutral-50' - - return `last-of-type:mb-0 rounded-lg ${bg} p-2 mt-4` - }, [resolvedTheme]) - - return !isClient - ?
...
- : ( -
- - {title} - -
{children}
-
- ) -} - -# PAGASA 10-Day Excel Files Discontinued - -**Effective August 31, 2025** - -## What's Changing - - -Starting **August 31, 2025**, PAGASA will no longer provide its **10-Day Weather Forecast in Excel format**. -Instead, all forecasts will be delivered through the new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) launched in **July 2025**. -This means any ACAP process, report, or system that currently relies on downloading Excel files will cease to function unless updated to use the API. - -_Note: PAGASA has not announced plans to archive past Excel files._ - - -
-Click to view the attached screenshot of PAGASA's announcement for more information. -![PAGASA 10-Day Excel files discontinuation announcement](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FNOZHqk2E8F8RoVvZuVVv_file?alt=media&token=88bd0b49-b7ee-45f8-843e-11bd0b9dcfe6) -
- -## FAQs - -The following FAQs explain who will be affected, why this change is happening, and how projects should prepare. - - -Projects that use the **PAGASA 10-Day Weather Forecast Excel files**. - -It includes **components in acap-v2** ([ACAP 2.0](/changelog/#version-2-acap-20)) and **climate-services-webportal-v1** ([ACAP 1.0](/changelog/#version-1-acap-10)), plus any forks, scripts, or automated tasks fetching Excel-based forecasts: - -1. [Provinces and municipalities listing](/articles/provinces-municipalities/) -2. [10-Day Weather Forecast data](/post-installation/weather-forecasts/tenday-forecast/) -3. _([ACAP-RCMAS REST APIs](/post-installation/acap-rcmas-api) - if these APIs are activated)_ -4. Automated scripts/workflows - - -After **August 31, 2025**, all workflows relying on Excel files will fail unless updated to use the API. - - - - - -PAGASA is modernizing data sharing by moving from Excel files to REST APIs, reducing brittle manual steps, and enabling more robust integrations. - -The new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) (launched July 2025) covers both **10-Day** and **Seasonal weather forecasts**. - - -It is not yet known whether PAGASA will also discontinue the **Seasonal Weather Forecast Excel files**. - - - - - - -There are currently no news or directives for syncing the parent **acap-v2** code repository to the **PAGASA TenDay API**. Projects using it as base template (including ACAP Bicol) are advised to sync their ACAPs to the API. - - -Here are the recommended migration steps for syncing ACAP to the PAGASA TenDay API. However, feel free to adjust and customize as deemed necessary. - -1. Review the [PAGASA TenDay API documentation](https://tenday.pagasa.dost.gov.ph/docs). -2. Request an **API key** from PAGASA. -3. **Regional location data:** Build the provinces and municipalities list from the PAGASA TenDay API, possibly from its **Validation - Location** endpoint at `"https://tenday.pagasa.dost.gov.ph/api/v1/location"`. -4. **Data source:** Replace the **10-Day weather forecast data** Excel fetch/parse logic with **TenDay API REST responses**. -5. Update scripts β€” Excel downloads will stop after August 31, 2025. - - -**Tip:** ACAP (1.0 until version 2.0 - 2.1) processes its **provinces and municipalities list** and **10-day weather forecast data** using the `"npm run cron:tenday"` NPM script, under the `"/server/src/scripts/cron/update_tenday_weather"` folder. - -Inspect and customize scripts in this folder to sync with the PAGASA TenDay API. - -Revisiting ACAP's architecture diagrams in the root `README` and `"/server/src/scripts/generate-docs/templates/img-acap.png"` may also help. - - - - - -Visit these references to learn more about the changes. - -- [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) -- [10-Day Weather Forecast](/post-installation/weather-forecasts/tenday-forecast/) -- [Provinces and Municipalities](/articles/provinces-municipalities) -- [ACAP-RCMAS REST APIs](/post-installation/acap-rcmas-api) - - ---- - +import { useEffect, useState, useMemo } from 'react' +import { useTheme } from 'next-themes' +import { Callout } from 'nextra/components' + +export function FAQBox({ title, children, open = false, color = '' }) { + // Copied from /articles/provinces-municipalities.mdx + const [isClient, setIsClient] = useState(false) + const { theme, resolvedTheme } = useTheme() + + useEffect(() => { + setIsClient(true) + }, []) + + const detailsBgStyle = useMemo(() => { + const bg = resolvedTheme === 'dark' + ? 'bg-neutral-800' + : 'bg-neutral-50' + + return `last-of-type:mb-0 rounded-lg ${bg} p-2 mt-4` + }, [resolvedTheme]) + + return !isClient + ?
...
+ : ( +
+ + {title} + +
{children}
+
+ ) +} + +# PAGASA 10-Day Excel Files Discontinued + +**Effective August 31, 2025** + +## What's Changing + + +Starting **August 31, 2025**, PAGASA will no longer provide its **10-Day Weather Forecast in Excel format**. +Instead, all forecasts will be delivered through the new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) launched in **July 2025**. +This means any ACAP process, report, or system that currently relies on downloading Excel files will cease to function unless updated to use the API. + +_Note: PAGASA has not announced plans to archive past Excel files._ + + +
+Click to view the attached screenshot of PAGASA's announcement for more information. +![PAGASA 10-Day Excel files discontinuation announcement](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FNOZHqk2E8F8RoVvZuVVv_file?alt=media&token=88bd0b49-b7ee-45f8-843e-11bd0b9dcfe6) +
+ +## FAQs + +The following FAQs explain who will be affected, why this change is happening, and how projects should prepare. + + +Projects that use the **PAGASA 10-Day Weather Forecast Excel files**. + +It includes **components in acap-v2** ([ACAP 2.0](/changelog/#version-2-acap-20)) and **climate-services-webportal-v1** ([ACAP 1.0](/changelog/#version-1-acap-10)), plus any forks, scripts, or automated tasks fetching Excel-based forecasts: + +1. [Provinces and municipalities listing](/articles/provinces-municipalities/) +2. [10-Day Weather Forecast data](/post-installation/weather-forecasts/tenday-forecast/) +3. _([ACAP-RCMAS REST APIs](/post-installation/acap-rcmas-api) - if these APIs are activated)_ +4. Automated scripts/workflows + + +After **August 31, 2025**, all workflows relying on Excel files will fail unless updated to use the API. + + + + + +PAGASA is modernizing data sharing by moving from Excel files to REST APIs, reducing brittle manual steps, and enabling more robust integrations. + +The new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) (launched July 2025) covers both **10-Day** and **Seasonal weather forecasts**. + + +It is not yet known whether PAGASA will also discontinue the **Seasonal Weather Forecast Excel files**. + + + + + + +There are currently no news or directives for syncing the parent **acap-v2** code repository to the **PAGASA TenDay API**. Projects using it as base template (including ACAP Bicol) are advised to sync their ACAPs to the API. + + +Here are the recommended migration steps for syncing ACAP to the PAGASA TenDay API. However, feel free to adjust and customize as deemed necessary. + +1. Review the [PAGASA TenDay API documentation](https://tenday.pagasa.dost.gov.ph/docs). +2. Request an **API key** from PAGASA. +3. **Regional location data:** Build the provinces and municipalities list from the PAGASA TenDay API, possibly from its **Validation - Location** endpoint at `"https://tenday.pagasa.dost.gov.ph/api/v1/location"`. +4. **Data source:** Replace the **10-Day weather forecast data** Excel fetch/parse logic with **TenDay API REST responses**. +5. Update scripts β€” Excel downloads will stop after August 31, 2025. + + +**Tip:** ACAP (1.0 until version 2.0 - 2.1) processes its **provinces and municipalities list** and **10-day weather forecast data** using the `"npm run cron:tenday"` NPM script, under the `"/server/src/scripts/cron/update_tenday_weather"` folder. + +Inspect and customize scripts in this folder to sync with the PAGASA TenDay API. + +Revisiting ACAP's architecture diagrams in the root `README` and `"/server/src/scripts/generate-docs/templates/img-acap.png"` may also help. + + + + + +Visit these references to learn more about the changes. + +- [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) +- [10-Day Weather Forecast](/post-installation/weather-forecasts/tenday-forecast/) +- [Provinces and Municipalities](/articles/provinces-municipalities) +- [ACAP-RCMAS REST APIs](/post-installation/acap-rcmas-api) + + +--- + *Disclaimer: This documentation update does not imply ongoing involvement with the project.* \ No newline at end of file diff --git a/docs/pages/articles.mdx b/docs/pages/articles.mdx new file mode 100644 index 00000000..2a20065a --- /dev/null +++ b/docs/pages/articles.mdx @@ -0,0 +1,16 @@ +import { Cards, Card, FileTree } from 'nextra/components' + +# Articles + +A collection of articles and notes about development and other details. + +
+ + + + + + + + + From 7f4062eb468838044cd9727ff412160fde41b1e3 Mon Sep 17 00:00:00 2001 From: acaptutorials Date: Sat, 30 Aug 2025 15:01:14 +0800 Subject: [PATCH 5/6] docs: move git-flow under post-installation --- docs/pages/articles/deployment.mdx | 45 ++----------------- docs/pages/post-installation.mdx | 15 +++++-- docs/pages/post-installation/_meta.json | 4 +- docs/pages/post-installation/git-flow.mdx | 53 +++++++++++++++++++++++ 4 files changed, 71 insertions(+), 46 deletions(-) create mode 100644 docs/pages/post-installation/git-flow.mdx diff --git a/docs/pages/articles/deployment.mdx b/docs/pages/articles/deployment.mdx index 773c1a63..ed6d4d56 100644 --- a/docs/pages/articles/deployment.mdx +++ b/docs/pages/articles/deployment.mdx @@ -12,50 +12,11 @@ Follow the steps in the **Render Initial Blueprint Instance** section to sync it ## Git Flow -CI/CD using GitHub Actions deploy code updates to the **development** or **production** environments following this [simplified version of Git Flow](https://youtu.be/cV-9KszXEyw?feature=shared&t=845). +CI/CD using GitHub Actions deploy code updates to the **development** or **production** environments following this [simplified version of Git Flow](https://youtu.be/cV-9KszXEyw?feature=shared&t=845). Refer to the [Git Flow](/post-installation/git-flow) page for more information about this process. -acap-git-flow - - -**(Optional)** Before proceeding, create a GitHub Issue describing the new feature, bug fix or task that you'll develop. This tracks the details of the incoming updates. - - - -### Create a feature branch - -- Create a **feature branch** branching out from the **dev branch** - - > If a GitHub Issue describes this feature, name the branch with the GitHub Issue number eg., `feat/acaptutorials-12` (Issue #12) - - ```sh - git checkout dev - git checkout -b feat/acaptutorials-12 - - # Using other branch names - # git checkout -b awesome-update - ``` - -- This isolates new work (feature, bug fix, or task) so it doesn't destabilize the shared development branch. - -### Merge the feature branch back to dev - -- Once the feature is complete and reviewed via a **Pull Request (PR)**, it's merged back into **dev**. -- Approving a PR to the dev branch (or pushing updates directly to the dev branch) triggers a deployment to the **development** (Firebase Hosting, Render and, [Vercel](/articles/deployment-vercel) (if available)) environment. -- It allows testing the feature with other in-progress features in an integrated (development) environment. -- Delete the feature branch afterward to keep the repository clean. - -### Promote dev to master +
-- When the **dev branch** has accumulated stable, tested features, create a Pull Request (PR) to **master** -- The master branch always reflects the code that's safe to release to production. - -### Tag a release - -- Tag and version a release from the **master branch** (e.g., v1.0.0). -- This creates an immutable snapshot of the code that corresponds to a specific release. -- It also triggers a deployment to the **production** (GitHub Pages, Render and, [Vercel](/articles/deployment-vercel) (if available)) environment. - - +acap-git-flow ## Render Initial Blueprint Instance diff --git a/docs/pages/post-installation.mdx b/docs/pages/post-installation.mdx index 0b661177..f5f4e12a 100644 --- a/docs/pages/post-installation.mdx +++ b/docs/pages/post-installation.mdx @@ -2,11 +2,11 @@ import { Cards, Card, Callout } from 'nextra/components' # Post-Installation -These tutorials contain additional post-installation instructions after initially setting up the client and server apps in the [Installation](/installation) section. +These tutorials contain additional post-installation instructions and guidelines after initially setting up the client and server apps in the [Installation](/installation) section.
-### Immediate +### ⚑ Immediate @@ -17,10 +17,19 @@ These tutorials contain additional post-installation instructions after initiall -### Optional +### ✨ Optional + +
+ +### πŸ’‘ During Development + + + + + \ No newline at end of file diff --git a/docs/pages/post-installation/_meta.json b/docs/pages/post-installation/_meta.json index bb1af904..e0cd7b5d 100644 --- a/docs/pages/post-installation/_meta.json +++ b/docs/pages/post-installation/_meta.json @@ -7,5 +7,7 @@ "acap-rcmas-api": "ACAP-RCMAS REST APIs", "opengraph": "Opengraph Settings", "google-search": "Google Search Console", - "province-codes": "Province Codes" + "province-codes": "Province Codes", + "git-flow": "Git Flow", + "site-search": "Site Search" } diff --git a/docs/pages/post-installation/git-flow.mdx b/docs/pages/post-installation/git-flow.mdx new file mode 100644 index 00000000..a2e9f8b4 --- /dev/null +++ b/docs/pages/post-installation/git-flow.mdx @@ -0,0 +1,53 @@ +import { Callout, Steps } from 'nextra/components' + +# Git Flow + +This page **summarizes the simplified version of Git Flow** branching strategy from the [ACAP video tutorials](https://youtu.be/cV-9KszXEyw?feature=shared&t=845) when developing new features, bug fixes or tasks. + +CI/CD using GitHub Actions deploy code updates to the **development** or **production** environments on certain triggers (eg., merging PRs to the dev branch or creating new Releases). + +
+ +acap-git-flow + + +**(Optional)** Before proceeding, create a GitHub Issue describing the new feature, bug fix or task that you'll develop. This tracks and organizes the details of the incoming updates. + + + +### Create a feature branch + +- Create a **feature branch** branching out from the **dev branch** + + > If a GitHub Issue describes this feature, name the branch with the GitHub Issue number eg., `feat/acaptutorials-12` (Issue #12) + + ```sh + git checkout dev + git checkout -b feat/acaptutorials-12 + + # Using other branch names + # git checkout -b awesome-update + ``` + +- This isolates new work (feature, bug fix, or task) so it doesn't destabilize the shared development branch. + +### Merge the feature branch back to dev + +- Once the feature is complete and reviewed via a **Pull Request (PR)**, it's merged back into **dev**. +- Approving a PR to the dev branch (or pushing updates directly to the dev branch) triggers a deployment to the **development** (Firebase Hosting, Render and, [Vercel](/articles/deployment-vercel) (if available)) environment. +- It allows testing the feature with other in-progress features in an integrated (development) environment. +- Delete the feature branch afterward to keep the repository clean. + +### Promote dev to master + +- When the **dev branch** has accumulated stable, tested features, create a Pull Request (PR) to **master** +- The master branch always reflects the code that's safe to release to production. + +### Tag a release + +- Tag and version a release from the **master branch** (e.g., v1.0.0). +- This creates an immutable snapshot of the code that corresponds to a specific release. +- It also triggers a deployment to the **production** (GitHub Pages, Render and, [Vercel](/articles/deployment-vercel) (if available)) environment. + + + From 3f10f15b9597a39a29b1a23fdcac77bde5ac79c4 Mon Sep 17 00:00:00 2001 From: acaptutorials Date: Sat, 30 Aug 2025 15:02:01 +0800 Subject: [PATCH 6/6] docs: add guides about site search --- .../announcements/pagasa-10day-excel.mdx | 11 +- docs/pages/post-installation/site-search.mdx | 136 ++++++++++++++++++ 2 files changed, 144 insertions(+), 3 deletions(-) create mode 100644 docs/pages/post-installation/site-search.mdx diff --git a/docs/pages/announcements/pagasa-10day-excel.mdx b/docs/pages/announcements/pagasa-10day-excel.mdx index f5431230..d49a3f84 100644 --- a/docs/pages/announcements/pagasa-10day-excel.mdx +++ b/docs/pages/announcements/pagasa-10day-excel.mdx @@ -51,6 +51,11 @@ _Note: PAGASA has not announced plans to archive past Excel files._
Click to view the attached screenshot of PAGASA's announcement for more information. ![PAGASA 10-Day Excel files discontinuation announcement](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FNOZHqk2E8F8RoVvZuVVv_file?alt=media&token=88bd0b49-b7ee-45f8-843e-11bd0b9dcfe6) + + +[alternate screenshot](https://private-user-images.githubusercontent.com/30580083/481051514-2d333f63-8fc4-4d81-a8da-d0ff48698c5e.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NTY1MzczNTAsIm5iZiI6MTc1NjUzNzA1MCwicGF0aCI6Ii8zMDU4MDA4My80ODEwNTE1MTQtMmQzMzNmNjMtOGZjNC00ZDgxLWE4ZGEtZDBmZjQ4Njk4YzVlLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNTA4MzAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjUwODMwVDA2NTczMFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTVkNDUzZmI0NjVhMTQxOWZhMmUxZDU4YmQ5ZTc1N2EzOGUwMWE1N2VlNWFhNGI3ODA4MTNkZDVmZDg5MjEwYzEmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.cUM-tiJyihJq5r8zyiTXW_h3_Astl3obI-XvymTy684) + +
## FAQs @@ -79,14 +84,14 @@ PAGASA is modernizing data sharing by moving from Excel files to REST APIs, redu The new [PAGASA TenDay API](https://tenday.pagasa.dost.gov.ph/docs) (launched July 2025) covers both **10-Day** and **Seasonal weather forecasts**. -It is not yet known whether PAGASA will also discontinue the **Seasonal Weather Forecast Excel files**. +It is not yet known whether PAGASA will also discontinue the [**Seasonal Weather Forecast Excel files**](/post-installation/weather-forecasts/seasonal-forecast/#pagasa-seasonal-weather-forecast-excel-file). -There are currently no news or directives for syncing the parent **acap-v2** code repository to the **PAGASA TenDay API**. Projects using it as base template (including ACAP Bicol) are advised to sync their ACAPs to the API. +There are currently no news or directives for syncing the parent **acap-v2** code repository to the **PAGASA TenDay API**. Projects using it as base template (including ACAP Bicol) are advised to sync their ACAPs to the API until futher notice. Here are the recommended migration steps for syncing ACAP to the PAGASA TenDay API. However, feel free to adjust and customize as deemed necessary. @@ -94,7 +99,7 @@ Here are the recommended migration steps for syncing ACAP to the PAGASA TenDay A 1. Review the [PAGASA TenDay API documentation](https://tenday.pagasa.dost.gov.ph/docs). 2. Request an **API key** from PAGASA. 3. **Regional location data:** Build the provinces and municipalities list from the PAGASA TenDay API, possibly from its **Validation - Location** endpoint at `"https://tenday.pagasa.dost.gov.ph/api/v1/location"`. -4. **Data source:** Replace the **10-Day weather forecast data** Excel fetch/parse logic with **TenDay API REST responses**. +4. **Data source:** Replace the **10-Day weather forecast Excel file** fetch/parse logic with **TenDay API REST responses**. 5. Update scripts β€” Excel downloads will stop after August 31, 2025. diff --git a/docs/pages/post-installation/site-search.mdx b/docs/pages/post-installation/site-search.mdx new file mode 100644 index 00000000..902bc2a9 --- /dev/null +++ b/docs/pages/post-installation/site-search.mdx @@ -0,0 +1,136 @@ +import { Callout, Steps } from 'nextra/components' + +# Search Bar: Site Search + +![search bar keywords](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FlE08vZGvNmHuOT870iFR_file?alt=media&token=cc3d3bec-739e-4f0d-8a63-8b6b3f0f2891) + +## Introduction + +This guide shows how to make **new public pages** searchable via the site's **Search Bar** by updating `data.js` and **running a keyword indexer script**. ACAP configures this feature via a script in`/server/src/scripts/page_indexer/`. + + +**`npm run build:page_index`** indexes keywords from live public pages defined in `data.js` and saves them to the database. It runs automatically after deployment, but you can also run it locally for testing. + + + +**Optional:** Only needed when adding **new public pages** or updating existing ones for search indexing. + +> **INFO:** The search method and keyword extraction process are expected to extract keywords only from simple static pages. Pages with longer or complex content may require a different approach. + + +## Add a Page to Search + +(Quick summary) + +1. Add `id` attributes to text containers in your page. +2. Update `data.js` with path, name, info, and selectors. +3. Run `npm run build:page_index` locally to test. +4. Commit and push changes. +5. Deploy and verify search results. + +## Detailed Steps + + + +### Prepare the new public page for indexing + +- Add unique HTML `id` attributes to the container `
` of target elements with text content that you'd like to extract keywords from. +- For example, if there is a new **About Us** page: + +```jsx copy +return ( + + Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor... + +) +``` + +### Inspect the public pages file definition + +- Open the `"/server/src/scripts/page_indexer/data.js"` file. +- Observe the Object structure of the elements in the `sites[]` array, eg., the entry for the public "Weather Services" page, + + ```js copy + const sites = [ + { + path: 'weather-services', + name: 'ACAP Services', + info: 'Seasonal and 10-Day Weather Forecasts, and Special Weather Advisory', + selectors: [ + '#contents-seasonal-forecast', + '#contents-tenday-forecast', + '#contents-special-weather-forecast' + ] + }, + ... + ] + ``` + +
+ πŸ‘‰ Click to view the **`sites[]` Object key definitions** + + | Key | Definition | + | --- | --- | + | path | Frontend (NextJS) route to the target page | + | name | Page title | + | info | Short summary or description about the page | + | selectors | Array of HTML `id` attributes in the page in which to extract keywords from. Each element starts with a `#` | + +
+ + + - Failing to add appropriate `"selectors"` will skip indexing the search keywords. + - Ensure all public pages load correctly. There will be errors in indexing if a page is inaccessible or has loading errors. + + +### Add a new page file entry + +- Create a new entry in the `"/server/src/scripts/page_indexer/data.js"` file under the `sites[]` array corresponding to a newly-created public page. +- For example, to add the **About Us** page from **step #1**: + + ```js copy + const sites = [ + { + path: 'about-us', + name: 'About Us', + info: 'Information and details about our company', + selectors: ['#about-us-content'] + }, + ... + ] + +### Test extracting keywords + +- Set `LIVE_ORIGIN=http://localhost:3000` in the server `.env` +- Run the local website + ```sh copy + npm run dev + ``` + +- Open `http://localhost:3000` to verify the site is running. + +- Run the server NPM script + ```sh copy + npm run build:page_index + ``` + + Fix errors that may occur during this step. + +- If there are no errors in the previous step, type keyword(s) from the sample **About Us** page in the **Search Bar**, eg., + ```text copy + lorem ipsum + ``` + + The **About Us** page should display in the search results. + + ![site search success](https://firebasestorage.googleapis.com/v0/b/assets-cms.appspot.com/o/users%2FAwryJ0MU8zdxQFh9y0L0x2sSt8z1%2FUg972YCHQreS1jQVGmif_file?alt=media&token=55f400fa-cb64-4870-9ee0-5daceb702019) + +### Commit the `data.js` file + +If there are no errors in the previous steps and the search keyword(s) appear in **step #4**, proceed to commit and push the updated `data.js` file. + +### Deploy + +When you push changes, GitHub Actions will automatically run `npm run build:page_index` during deployment. Verify that the new keywords appear in the live Search Bar. + +