attogram · attogram · Sep 6, 2025 · Sep 6, 2025 · Sep 6, 2025 · Sep 6, 2025
diff --git a/docs/README.md b/docs/README.md
@@ -12,20 +12,16 @@ This directory contains the documentation for the `base` project.
 
 ## CI/CD
 
-- [Secrets Management](./cicd.secrets-management.md) - Best practices for managing secrets in GitHub Actions.
-- [Workflow Scheduling](./cicd.workflow-scheduling.md) - Automating recurring tasks with cron.
-- [GitHub Workflows](./cicd.workflows.md) - Explanation of the CI/CD workflows.
+- [Secrets Management](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions.
+- [Workflow Scheduling](./workflows.scheduling.md) - Automating recurring tasks with cron.
+- [GitHub Workflows](./workflows.md) - Explanation of the CI/CD workflows.
 
 ## Community
 
 - [Community Building Guide](./community.building.md) - Fostering a healthy and effective community.
 - [Using GitHub Discussions](./community.discussions.md) - Leveraging Discussions for community conversations.
 - [Issue Management Guide](./community.issue-management.md) - Best practices for triaging issues.
 
-## Deployment
-
-- [Deploying to Render.com](./deployment.render.md) - Instructions for deploying to Render.com.
-
 ## Development
 
 - [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development.

diff --git a/docs/cicd.workflows.md b/docs/cicd.workflows.md
diff --git a/docs/deployment.render.md b/docs/deployment.render.md
@@ -1,5 +1,8 @@
 # Deploying to Render.com
 
+> [!WARNING]
+> This feature is in development and is not yet ready for use.
+
 This repository is configured for continuous deployment to [Render.com](https://render.com/)
 on their free tier.
 
@@ -27,3 +30,14 @@ To deploy this repository to your own Render account:
 
 Any subsequent pushes to your `main` branch will automatically trigger a new
 deployment on Render.
+
+## `render.yaml`
+
+```yaml
+services:
+  - type: web
+    name: base-template-app
+    env: docker
+    plan: free
+    healthCheckPath: /
+```
diff --git a/docs/development.prettier-workflow.md b/docs/development.prettier-workflow.md
diff --git a/docs/development.prettier.md b/docs/development.prettier.md
@@ -1,92 +1,42 @@
-# Prettier
+# Prettier for Code Formatting
 
-Prettier is an opinionated code formatter.
-It enforces a consistent style by parsing your code and re-printing it with
-its own rules that take the maximum line length into account, wrapping code
-when necessary.
+[Prettier](https://prettier.io/) is an opinionated code formatter that enforces a consistent code style across the entire project. This repository is configured to use Prettier in two ways: automatically via a GitHub workflow and manually for local development.
 
-This document provides instructions on how to install and run Prettier in your
-project.
+## Automated Formatting with GitHub Actions
 
-## Installation
+This repository includes a [GitHub Actions workflow](./workflows.prettier.md) that automatically formats all code.
 
-The recommended approach is to install Prettier locally as a development
-dependency.
+- **How it works**: The workflow runs on every push to the `main` branch and on every pull request. It runs `prettier --write .` to format all files and commits any changes with the message "style: Format code with Prettier".
+- **What you need to do**: Nothing! The workflow handles everything automatically. If you push code that isn't formatted, the workflow will create a new commit with the required formatting changes.
 
-### npm
+This ensures that all code merged into the `main` branch is consistently formatted.
 
-```bash
-npm install --save-dev --save-exact prettier
-```
-
-### yarn
-
-```bash
-yarn add --dev --exact prettier
-```
-
-### pnpm
-
-```bash
-pnpm add --save-dev --save-exact prettier
-```
-
-### bun
-
-```bash
-bun add --dev --exact prettier
-```
+## Manual Formatting
 
-This repository includes a default configuration file,
-[`.prettierrc`](../.prettierrc), so you don't need to create one from
-scratch.
-It lets editors and other tools know that you are using Prettier.
+While the automated workflow handles formatting on the server, it's a good practice to run Prettier locally as you work.
 
-It is also useful to create a `.prettierignore` file to specify which files
-should not be formatted by Prettier.
+### Installation
 
-```bash
-echo "# Ignore artifacts:\nbuild\ncoverage" > .prettierignore
-```
-
-## Usage
-
-Once Prettier is installed, you can run it from the command line to format
-your files.
-
-### Format all files
-
-To format all files in your project, run the following command:
+This repository includes Prettier as a development dependency in `package.json`. To install it, run:
 
 ```bash
-npx prettier . --write
+npm install
 ```
 
-### Format specific files or directories
-
-You can also format specific files or directories:
+The repository also includes a [`.prettierrc`](../.prettierrc) configuration file, so you don't need to create one.
 
-```bash
-# Format all files in the 'app' directory
-npx prettier app --write
-
-# Format a single file
-npx prettier app/components/Button.js --write
-
-# Format all test files in a directory using a glob pattern
-npx prettier "app/**/*.test.js" --write
-```
+### Usage
 
-### Check for formatting issues
+You can run Prettier from the command line to format your files.
 
-In a Continuous Integration (CI) environment, you can use the `--check` flag
-to verify that all files are formatted correctly without actually modifying
-them.
-This is useful for enforcing a consistent code style.
-
-```bash
-npx prettier . --check
-```
+- **Format all files**:
+  ```bash
+  npx prettier . --write
+  ```
+- **Check for formatting issues without changing files**:
+  ```bash
+  npx prettier . --check
+  ```
+  The [CI workflow](./workflows.ci.md) uses this command to validate formatting on pull requests.
 
-For more information, please refer to the official
-[Prettier documentation](https://prettier.io/docs/en/install.html).
+For more detailed information on using Prettier, refer to the [official Prettier documentation](https://prettier.io/docs/en/).
diff --git a/docs/workflows.ci.md b/docs/workflows.ci.md
@@ -0,0 +1,23 @@
+# CI Workflow
+
+The CI (Continuous Integration) workflow is defined in `.github/workflows/ci.yml`.
+
+## Triggers
+
+This workflow is triggered by the following events:
+
+- `push` to the `main` branch
+- `pull_request` to the `main` branch
+
+## Jobs
+
+### `lint`
+
+This job, named "Lint Code Base", runs on the latest version of Ubuntu. It performs the following steps:
+
+1.  **Checkout Code**: Checks out the repository's code.
+2.  **Setup Node.js**: Sets up Node.js version 20.
+3.  **Install Prettier**: Installs the Prettier code formatter globally.
+4.  **Run Prettier**: Runs `prettier --check .` to verify that all files in the repository are formatted correctly according to the Prettier configuration.
+
+The purpose of this workflow is to ensure that all code pushed to the `main` branch or included in a pull request to `main` adheres to the project's coding style, as defined by Prettier. This helps maintain code consistency and quality.
diff --git a/docs/workflows.md b/docs/workflows.md
@@ -0,0 +1,19 @@
+# CI/CD Workflows
+
+This repository includes several GitHub Actions workflows to automate various tasks. Each workflow is defined in a `.yml` file in the `.github/workflows` directory.
+
+Below is an overview of the available workflows. For more detailed information about a specific workflow, please refer to its dedicated documentation page.
+
+## Workflow Index
+
+- [**CI Workflow**](./workflows.ci.md) (`ci.yml`)
+- Ensures code quality by running linting checks on every push and pull request to the `main` branch.
+
+- [**GitHub Pages Deployment**](./workflows.pages.md) (`pages.yml`)
+- Builds and deploys the repository's content as a GitHub Pages website.
+
+- [**Prettier Workflow**](./workflows.prettier.md) (`prettier.yml`)
+- Automatically formats the code in the repository using Prettier and commits the changes.
+
+- [**Release on Tag**](./workflows.release-on-tag.md) (`release-on-tag.yml`)
+- Automates the creation of GitHub Releases when a new version tag is pushed.
diff --git a/docs/workflows.pages.md b/docs/workflows.pages.md
@@ -0,0 +1,39 @@
+# GitHub Pages Deployment Workflow
+
+The GitHub Pages deployment workflow is defined in `.github/workflows/pages.yml`. Its purpose is to build and deploy the repository's content as a GitHub Pages website.
+
+## Triggers
+
+This workflow is triggered by:
+
+- A `push` to the `main` branch.
+- A manual `workflow_dispatch` event, allowing it to be run from the Actions tab in GitHub.
+
+## Permissions
+
+The workflow is granted the following permissions:
+
+- `contents: read` to read the repository's content.
+- `pages: write` to deploy to GitHub Pages.
+- `id-token: write` to authenticate with GitHub Pages.
+
+## Concurrency
+
+The workflow uses a concurrency group named `"pages"` to ensure that only one deployment runs at a time. If a new workflow run is triggered while another is in progress, the new run will be queued. However, in-progress runs are not cancelled.
+
+## Jobs
+
+### `build`
+
+This job runs on `ubuntu-latest` and performs the following steps to build the site:
+
+1.  **Checkout**: Checks out the repository's code.
+2.  **Setup Pages**: Configures the GitHub Pages environment.
+3.  **Build with Jekyll**: Uses the `actions/jekyll-build-pages` action to build the site with Jekyll. The source is the root of the repository (`./`), and the destination for the built site is `./_site`.
+4.  **Upload artifact**: Uploads the built site as a GitHub Pages artifact.
+
+### `deploy`
+
+This job also runs on `ubuntu-latest` and depends on the successful completion of the `build` job. It performs the following steps to deploy the site:
+
+1.  **Deploy to GitHub Pages**: Uses the `actions/deploy-pages` action to deploy the artifact from the `build` job to GitHub Pages. The environment is configured for `github-pages`, and the URL of the deployed site is made available as an output.
diff --git a/docs/workflows.prettier.md b/docs/workflows.prettier.md
@@ -0,0 +1,24 @@
+# Prettier Workflow
+
+The Prettier workflow, defined in `.github/workflows/prettier.yml`, automates code formatting for the entire repository.
+
+## Triggers
+
+This workflow is triggered on:
+
+- `push` to the `main` branch
+- Any `pull_request`
+
+## Jobs
+
+### `format`
+
+This job runs on `ubuntu-latest` and performs the following steps:
+
+1.  **Checkout Code**: Checks out the repository's code. It uses the `GITHUB_TOKEN` to allow the workflow to push changes back to the repository.
+2.  **Setup Node.js**: Sets up Node.js version 20 and configures caching for `npm` to speed up dependency installation.
+3.  **Install Dependencies**: Installs the project's dependencies, including Prettier, by running `npm install`.
+4.  **Run Prettier**: Executes `npx prettier --write .` to format all files in the repository in-place.
+5.  **Commit Changes**: Uses the `stefanzweifel/git-auto-commit-action` to check if Prettier made any changes. If there are changes, it commits them back to the current branch with the commit message "style: Format code with Prettier". This action is configured to check all files.
+
+The purpose of this workflow is to ensure that all code in the repository is consistently formatted according to the Prettier rules, without requiring developers to run Prettier manually before committing.
diff --git a/docs/workflows.release-on-tag.md b/docs/workflows.release-on-tag.md
@@ -0,0 +1,27 @@
+# Release on Tag Workflow
+
+The "Create Release" workflow, defined in `.github/workflows/release-on-tag.yml`, automates the process of creating a new GitHub release whenever a new tag is pushed to the repository.
+
+## Triggers
+
+This workflow is triggered when a `push` event occurs with a tag that matches the pattern `v*.*.*` (e.g., `v1.0.0`, `v2.3.4`).
+
+## Jobs
+
+### `build`
+
+This job runs on `ubuntu-latest` and has `contents: write` permissions to allow it to create a release. It performs the following steps:
+
+1.  **Checkout code**: Checks out the repository's code. `fetch-depth: 0` is used to fetch all history for all branches and tags, which is necessary for generating the changelog.
+
+2.  **Generate release notes**: This step generates the body of the release notes. It does this by:
+    - Identifying the previous tag to determine the range of commits to include in the changelog.
+    - Generating a changelog from the Git history between the previous tag and the current `HEAD`. The changelog format is a list of commit messages, each with a link to the corresponding commit.
+    - Reading the release body template from `.github/RELEASE_BODY.md` and substituting the `${TAG}` placeholder with the current tag name.
+    - Combining the user-provided body, the generated changelog, and a link to the full diff on GitHub into a single `FINAL_BODY` output.
+
+3.  **Get Release Title**: This step reads the release title template from `.github/RELEASE_TITLE.txt`, replaces the `${TAG}` placeholder with the current tag name, and sets the result as an output named `title`.
+
+4.  **Create Release**: This final step uses the `softprops/action-gh-release` action to create the GitHub release. It uses the title and body generated in the previous steps, and sets the `tag_name` to the tag that triggered the workflow. The release is created as a full release (not a draft or pre-release).
+
+This workflow streamlines the release process by automating the creation of well-formatted, consistent GitHub releases based on Git tags.
diff --git a/docs/cicd.workflow-scheduling.md → docs/workflows.scheduling.md b/docs/cicd.workflow-scheduling.md → docs/workflows.scheduling.md
diff --git a/docs/cicd.secrets-management.md → docs/workflows.secrets-management.md b/docs/cicd.secrets-management.md → docs/workflows.secrets-management.md
diff --git a/render.yaml b/render.yaml