From ce7c61a6e03ac386213b2379247895127b2469aa Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 6 Sep 2025 11:46:10 +0000 Subject: [PATCH 1/5] docs: consolidate workflow documentation into README.md - Moves the content from individual workflow documentation files into the main `docs/README.md`. - Deletes the now-redundant individual workflow files. - Fixes a broken link to a non-existent prettier workflow document. --- docs/README.md | 173 ++++++++++++++++++++++++++- docs/workflows.ci.md | 23 ---- docs/workflows.md | 19 --- docs/workflows.pages.md | 39 ------ docs/workflows.prettier.md | 24 ---- docs/workflows.release-on-tag.md | 27 ----- docs/workflows.scheduling.md | 108 ----------------- docs/workflows.secrets-management.md | 78 ------------ 8 files changed, 169 insertions(+), 322 deletions(-) delete mode 100644 docs/workflows.ci.md delete mode 100644 docs/workflows.md delete mode 100644 docs/workflows.pages.md delete mode 100644 docs/workflows.prettier.md delete mode 100644 docs/workflows.release-on-tag.md delete mode 100644 docs/workflows.scheduling.md delete mode 100644 docs/workflows.secrets-management.md diff --git a/docs/README.md b/docs/README.md index c99295a..b8cd9e6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,9 +12,175 @@ This directory contains the documentation for the `base` project. ## CI/CD -- [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. +This repository includes several GitHub Actions workflows to automate various tasks. Each workflow is defined in a `.yml` file in the `.github/workflows` directory. + +### 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** + +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. + +### 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. + +### 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** + +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. + +### 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** + +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. + +### Scheduling Workflows with Cron + +GitHub Actions allows you to automate tasks on a schedule, similar to the traditional cron utility in Unix-like systems. This is useful for recurring tasks like nightly builds, daily reports, or weekly dependency checks. + +**How it Works** + +You can trigger a workflow to run at specific UTC times using the `schedule` event. This event is configured with a `cron` expression. + +```yaml +on: + schedule: + - cron: "30 5 * * 1-5" +``` + +This example triggers the workflow at 5:30 AM UTC every day from Monday to Friday. + +**Understanding Cron Syntax** + +A cron expression is a string of five fields that represent a time schedule. + +``` +┌───────────── minute (0 - 59) +│ ┌───────────── hour (0 - 23) +│ │ ┌───────────── day of the month (1 - 31) +│ │ │ ┌───────────── month (1 - 12) +│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday) +│ │ │ │ │ +│ │ │ │ │ +* * * * * +``` + +**Special Characters** + +- `*`: Matches any value. `* * * * *` runs every minute. +- `,`: Separates multiple values. `0,15,30,45 * * * *` runs at minutes 0, 15, 30, and 45. +- `-`: Defines a range of values. `0 9-17 * * *` runs every hour from 9 AM to 5 PM. +- `/`: Specifies a step value. `*/15 * * * *` runs every 15 minutes. + +### Secrets Management in GitHub Actions + +Properly managing secrets like API keys, access tokens, and other credentials is a critical aspect of security. This guide explains the best practice of using GitHub Actions secrets to handle sensitive information. + +**Why Secret Management is Important** + +**Never commit secrets directly to your repository.** Once a secret is in your git history, it should be considered compromised, even if you later remove it from the current version of the code. A public repository is visible to everyone, and malicious actors actively scan for exposed credentials. + +**How to Use a Secret in a Workflow** + +Once a secret is stored, you can access it in your workflow `.yml` files using the `secrets` context. + +Here's an example of a workflow step that uses a secret to publish a package to the npm registry: + +```yaml +- name: Publish to npm + uses: actions/setup-node@v3 + with: + node-version: "18" + registry-url: "https://registry.npmjs.org" +- run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} +``` ## Community @@ -28,7 +194,6 @@ This directory contains the documentation for the `base` project. - [Docker Environment](./development.docker.md) - Using the included Docker setup. - [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files. - [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier. -- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code. ## Documentation diff --git a/docs/workflows.ci.md b/docs/workflows.ci.md deleted file mode 100644 index da01955..0000000 --- a/docs/workflows.ci.md +++ /dev/null @@ -1,23 +0,0 @@ -# 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 deleted file mode 100644 index 8d5d451..0000000 --- a/docs/workflows.md +++ /dev/null @@ -1,19 +0,0 @@ -# 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 deleted file mode 100644 index edb58bc..0000000 --- a/docs/workflows.pages.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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 deleted file mode 100644 index 2d92715..0000000 --- a/docs/workflows.prettier.md +++ /dev/null @@ -1,24 +0,0 @@ -# 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 deleted file mode 100644 index 127c1e0..0000000 --- a/docs/workflows.release-on-tag.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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/workflows.scheduling.md b/docs/workflows.scheduling.md deleted file mode 100644 index f891436..0000000 --- a/docs/workflows.scheduling.md +++ /dev/null @@ -1,108 +0,0 @@ -# Scheduling Workflows with Cron - -GitHub Actions allows you to automate tasks on a schedule, similar to the -traditional cron utility in Unix-like systems. -This is useful for recurring tasks like nightly builds, daily reports, or -weekly dependency checks. - -## How it Works - -You can trigger a workflow to run at specific UTC times using the `schedule` -event. -This event is configured with a `cron` expression. - -```yaml -on: - schedule: - - cron: "30 5 * * 1-5" -``` - -This example triggers the workflow at 5:30 AM UTC every day from Monday to -Friday. - -## Understanding Cron Syntax - -A cron expression is a string of five fields that represent a time schedule. - -``` -┌───────────── minute (0 - 59) -│ ┌───────────── hour (0 - 23) -│ │ ┌───────────── day of the month (1 - 31) -│ │ │ ┌───────────── month (1 - 12) -│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday) -│ │ │ │ │ -│ │ │ │ │ -* * * * * -``` - -### Special Characters - -- `*`: Matches any value. - `* * * * *` runs every minute. -- `,`: Separates multiple values. - `0,15,30,45 * * * *` runs at minutes 0, 15, 30, and 45. -- `-`: Defines a range of values. - `0 9-17 * * *` runs every hour from 9 AM to 5 PM. -- `/`: Specifies a step value. - `*/15 * * * *` runs every 15 minutes. - -### Examples - -| Cron Expression | Description | -| ----------------- | -------------------------------------------------- | -| `0 0 * * *` | Run at midnight UTC every day. | -| `0 9 * * 1` | Run at 9:00 AM UTC every Monday. | -| `0 * * * *` | Run at the beginning of every hour. | -| `*/30 9-17 * * *` | Run every 30 minutes between 9 AM and 5 PM UTC. | -| `0 0 1 * *` | Run at midnight UTC on the first day of the month. | - -## Example Workflow - -Here is a complete example of a workflow that runs a script every day at -midnight UTC. - -```yaml -# .github/workflows/nightly-build.yml -name: Nightly Build - -on: - schedule: - - cron: "0 0 * * *" - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Check out repository - uses: actions/checkout@v3 - - - name: Run nightly script - run: ./scripts/run-nightly.sh -``` - -## Best Practices - -1. **Use UTC:** All scheduled times are in Coordinated Universal Time (UTC). - Be sure to account for time zone differences. - -2. **Minimum Frequency:** The shortest interval you can schedule a workflow to - run is every 5 minutes. - -3. **Use `workflow_dispatch`:** It's a good practice to add - `workflow_dispatch` alongside `schedule`. - This allows you to manually trigger the workflow from the GitHub UI, which - is very useful for testing. - -4. **Be Mindful of Usage:** Scheduled workflows consume your GitHub Actions - minutes. - If a task doesn't need to run frequently, choose a longer interval. - -5. **Handle Failures:** Consider adding a step to your workflow to send a - notification (e.g., via email or Slack) if a scheduled job fails. - This way, you can quickly address any issues. - -By leveraging scheduled workflows, you can automate a wide range of -maintenance and operational tasks, helping to keep your project healthy and -up-to-date. diff --git a/docs/workflows.secrets-management.md b/docs/workflows.secrets-management.md deleted file mode 100644 index 531fd3e..0000000 --- a/docs/workflows.secrets-management.md +++ /dev/null @@ -1,78 +0,0 @@ -# Secrets Management in GitHub Actions - -Properly managing secrets like API keys, access tokens, and other credentials -is a critical aspect of security. -This guide explains the best practice of using GitHub Actions secrets to handle -sensitive information. - -## Why Secret Management is Important - -**Never commit secrets directly to your repository.** -Once a secret is in your git history, it should be considered compromised, -even if you later remove it from the current version of the code. -A public repository is visible to everyone, and malicious actors actively -scan for exposed credentials. - -Leaked secrets can lead to: - -- Unauthorized access to your accounts and services. -- Financial loss (e.g., if an API key for a paid service is stolen). -- Damage to your project's reputation. - -## Using GitHub Actions Secrets - -GitHub provides a secure way to store and use secrets within your repository -for use in GitHub Actions workflows. - -### How it Works - -1. **Encrypted Storage:** Secrets are stored as encrypted values at the - repository or organization level. -2. **Limited Access:** Secrets are only exposed to the specific GitHub Actions - workflows you choose. - They are not accessible to collaborators or even the repository owner once - they are set. -3. **Redacted Logs:** GitHub automatically redacts secrets from workflow logs, - preventing them from being accidentally exposed in build outputs. - -### How to Add a Repository Secret - -1. Navigate to your repository on GitHub. -2. Go to **Settings** > **Secrets and variables** > **Actions**. -3. Click the **New repository secret** button. -4. Enter a name for your secret (e.g., `NPM_TOKEN`, `AWS_ACCESS_KEY_ID`). - This name will be used to reference the secret in your workflow files. -5. Paste the secret value into the **Value** field. -6. Click **Add secret**. - -![GitHub new secret page](https://docs.github.com/assets/cb-57155/images/help/repository/actions-secrets-tab.png) - -### How to Use a Secret in a Workflow - -Once a secret is stored, you can access it in your workflow `.yml` files using -the `secrets` context. - -Here's an example of a workflow step that uses a secret to publish a package -to the npm registry: - -```yaml -- name: Publish to npm - uses: actions/setup-node@v3 - with: - node-version: "18" - registry-url: "https://registry.npmjs.org" -- run: npm publish - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} -``` - -In this example: - -- `secrets.NPM_TOKEN` refers to a repository secret named `NPM_TOKEN`. -- The secret's value is assigned to the `NODE_AUTH_TOKEN` environment - variable, which is used by the `npm publish` command for authentication. - -By using GitHub Actions secrets, you can automate workflows that require access -to sensitive information without compromising on security. -It's a fundamental practice for any project that interacts with external -services. From 7d72ba84fb508544c50a784c916f12ad4b90ffa4 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 6 Sep 2025 11:57:21 +0000 Subject: [PATCH 2/5] docs: restructure documentation into namespaces - Refactors the documentation in the `docs/` directory to use a two-level namespace structure. - `docs/README.md` is now a master Table of Contents linking to namespace index files. - Creates a top-level `namespace.md` file for each documentation category (e.g., `ai.md`, `community.md`). - Each `namespace.md` file contains an overview and links to the specific documentation pages within that namespace. - Updates `AGENTS.md` to include guidelines for the new documentation structure. --- AGENTS.md | 13 +- docs/README.md | 232 ++------------------------- docs/ai.md | 6 + docs/community.md | 7 + docs/deployment.md | 5 + docs/development.md | 9 ++ docs/documentation.md | 5 + docs/guides.md | 5 + docs/project.md | 11 ++ docs/updating.md | 6 + docs/workflows.ci.md | 23 +++ docs/workflows.md | 14 ++ docs/workflows.pages.md | 39 +++++ docs/workflows.prettier.md | 24 +++ docs/workflows.release-on-tag.md | 27 ++++ docs/workflows.scheduling.md | 108 +++++++++++++ docs/workflows.secrets-management.md | 78 +++++++++ 17 files changed, 388 insertions(+), 224 deletions(-) create mode 100644 docs/ai.md create mode 100644 docs/community.md create mode 100644 docs/deployment.md create mode 100644 docs/development.md create mode 100644 docs/documentation.md create mode 100644 docs/guides.md create mode 100644 docs/project.md create mode 100644 docs/updating.md create mode 100644 docs/workflows.ci.md create mode 100644 docs/workflows.md create mode 100644 docs/workflows.pages.md create mode 100644 docs/workflows.prettier.md create mode 100644 docs/workflows.release-on-tag.md create mode 100644 docs/workflows.scheduling.md create mode 100644 docs/workflows.secrets-management.md diff --git a/AGENTS.md b/AGENTS.md index eeacb65..24d5cad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,9 +49,10 @@ repository: - [`SECURITY.md`](./.github/SECURITY.md): A template for the user's security policy. -- **[`docs/`](./docs/)**: Contains all documentation for the project. - Each major feature or component has its own corresponding `.md` file in this - directory. +- **[`docs/`](./docs/)**: Contains all documentation for the project. The documentation is organized into namespaces. + - **`docs/README.md`**: The main entry point for documentation, which serves as a Table of Contents. + - **`docs/.md`**: Each namespace has a top-level index file (e.g., `docs/ai.md`) that provides an overview and links to all the sub-pages within that namespace. + - **`docs/..md`**: Individual documentation pages for specific topics within a namespace. - **[`docker/`](./docker/)**: Contains the development environment. - [`Dockerfile`](./docker/Dockerfile): Builds a generic Ubuntu + NGINX @@ -88,7 +89,11 @@ repository: - **Update Documentation:** If you change a feature, you **must** update its corresponding documentation in the [`docs/`](./docs/) directory. If you add a new feature, you **must** create a new documentation file for - it. + it, following the namespace structure. This means: + 1. Identify the correct namespace for your documentation (e.g., `development`, `workflows`). + 2. Create a new file named `docs/..md`. + 3. Add a link to your new file in the corresponding namespace index file (e.g., `docs/.md`). + 4. If you are creating a new namespace, you must also create a `docs/.md` index file and link to it from the main `docs/README.md`. - **Verify Your Work:** After creating or modifying a file, use a read-only tool like `read_file` or `ls` to confirm your changes were applied correctly before marking a step as complete. diff --git a/docs/README.md b/docs/README.md index b8cd9e6..7d7f2c6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,223 +5,15 @@ This directory contains the documentation for the `base` project. - [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template. - [Documentation Index](./README.md) - You are here. -## AI - -- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents. -- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents. - -## CI/CD - -This repository includes several GitHub Actions workflows to automate various tasks. Each workflow is defined in a `.yml` file in the `.github/workflows` directory. - -### 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** - -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. - -### 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. - -### 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** - -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. - -### 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** - -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. - -### Scheduling Workflows with Cron - -GitHub Actions allows you to automate tasks on a schedule, similar to the traditional cron utility in Unix-like systems. This is useful for recurring tasks like nightly builds, daily reports, or weekly dependency checks. - -**How it Works** - -You can trigger a workflow to run at specific UTC times using the `schedule` event. This event is configured with a `cron` expression. - -```yaml -on: - schedule: - - cron: "30 5 * * 1-5" -``` - -This example triggers the workflow at 5:30 AM UTC every day from Monday to Friday. - -**Understanding Cron Syntax** - -A cron expression is a string of five fields that represent a time schedule. - -``` -┌───────────── minute (0 - 59) -│ ┌───────────── hour (0 - 23) -│ │ ┌───────────── day of the month (1 - 31) -│ │ │ ┌───────────── month (1 - 12) -│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday) -│ │ │ │ │ -│ │ │ │ │ -* * * * * -``` - -**Special Characters** - -- `*`: Matches any value. `* * * * *` runs every minute. -- `,`: Separates multiple values. `0,15,30,45 * * * *` runs at minutes 0, 15, 30, and 45. -- `-`: Defines a range of values. `0 9-17 * * *` runs every hour from 9 AM to 5 PM. -- `/`: Specifies a step value. `*/15 * * * *` runs every 15 minutes. - -### Secrets Management in GitHub Actions - -Properly managing secrets like API keys, access tokens, and other credentials is a critical aspect of security. This guide explains the best practice of using GitHub Actions secrets to handle sensitive information. - -**Why Secret Management is Important** - -**Never commit secrets directly to your repository.** Once a secret is in your git history, it should be considered compromised, even if you later remove it from the current version of the code. A public repository is visible to everyone, and malicious actors actively scan for exposed credentials. - -**How to Use a Secret in a Workflow** - -Once a secret is stored, you can access it in your workflow `.yml` files using the `secrets` context. - -Here's an example of a workflow step that uses a secret to publish a package to the npm registry: - -```yaml -- name: Publish to npm - uses: actions/setup-node@v3 - with: - node-version: "18" - registry-url: "https://registry.npmjs.org" -- run: npm publish - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} -``` - -## 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. - -## Development - -- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development. -- [Docker Environment](./development.docker.md) - Using the included Docker setup. -- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files. -- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier. - -## Documentation - -- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. - -## Guides - -- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. - -## Updating - -- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template. -- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it. - -## Project Management - -- [Repository Badges](./project.badges.md) - How to use and create repository badges. -- [Launch Checklist](./project.launch-checklist.md) - A reusable checklist for project launches. -- [Licensing Info](./project.licensing.md) - Details on the MIT License. -- [Security Best Practices](./project.security.md) - Basic security practices for maintainers. -- [Standard Files](./project.standard-files.md) - Explanation of standard repo files. -- [Template Repo Guide](./project.template-repo.md) - Best practices for maintaining this template. -- [Versioning Guide](./project.versioning.md) - Professional release management. - -## Publishing - -- [Publishing Overview](./publishing.md) - An overview of the different ways to publish content. -- [Publishing with Markdown](./publishing.markdown.md) - The simplest way to create pages. -- [Advanced Publishing with HTML](./publishing.html.md) - For more control over layout and style. -- [Publishing with Magic Links](./publishing.magic-links.md) - Creating links that pre-fill new file content. -- [GitHub Pages](./publishing.github-pages.md) - How the underlying publishing system works. +## Namespaces + +- [AI](./ai.md) - Documentation related to Artificial Intelligence. +- [CI/CD](./workflows.md) - Documentation for the CI/CD workflows. +- [Community](./community.md) - Documentation related to community management. +- [Deployment](./deployment.md) - Documentation related to deployment. +- [Development](./development.md) - Documentation related to development practices and environment setup. +- [Documentation](./documentation.md) - Documentation about writing documentation. +- [Guides](./guides.md) - Guides for using this project. +- [Project Management](./project.md) - Documentation related to project management. +- [Publishing](./publishing.md) - Documentation about publishing content. +- [Updating](./updating.md) - Documentation about updating the repository. diff --git a/docs/ai.md b/docs/ai.md new file mode 100644 index 0000000..464256d --- /dev/null +++ b/docs/ai.md @@ -0,0 +1,6 @@ +# AI + +This section contains documentation related to Artificial Intelligence. + +- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents. +- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents. diff --git a/docs/community.md b/docs/community.md new file mode 100644 index 0000000..078fef4 --- /dev/null +++ b/docs/community.md @@ -0,0 +1,7 @@ +# Community + +This section contains documentation related to community management. + +- [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. diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..23d0cad --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,5 @@ +# Deployment + +This section contains documentation related to deployment. + +- [Render Deployment](./deployment.render.md) - How to deploy the application to Render. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..62a2d3f --- /dev/null +++ b/docs/development.md @@ -0,0 +1,9 @@ +# Development + +This section contains documentation related to development practices and environment setup. + +- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development. +- [Docker Environment](./development.docker.md) - Using the included Docker setup. +- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files. +- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier. +- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code. diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 0000000..bc5034c --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,5 @@ +# Documentation + +This section contains documentation about writing documentation. + +- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. diff --git a/docs/guides.md b/docs/guides.md new file mode 100644 index 0000000..eb8faae --- /dev/null +++ b/docs/guides.md @@ -0,0 +1,5 @@ +# Guides + +This section contains guides for using this project. + +- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. diff --git a/docs/project.md b/docs/project.md new file mode 100644 index 0000000..9983b08 --- /dev/null +++ b/docs/project.md @@ -0,0 +1,11 @@ +# Project Management + +This section contains documentation related to project management. + +- [Repository Badges](./project.badges.md) - How to use and create repository badges. +- [Launch Checklist](./project.launch-checklist.md) - A reusable checklist for project launches. +- [Licensing Info](./project.licensing.md) - Details on the MIT License. +- [Security Best Practices](./project.security.md) - Basic security practices for maintainers. +- [Standard Files](./project.standard-files.md) - Explanation of standard repo files. +- [Template Repo Guide](./project.template-repo.md) - Best practices for maintaining this template. +- [Versioning Guide](./project.versioning.md) - Professional release management. diff --git a/docs/updating.md b/docs/updating.md new file mode 100644 index 0000000..394d4b8 --- /dev/null +++ b/docs/updating.md @@ -0,0 +1,6 @@ +# Updating + +This section contains documentation about updating the repository. + +- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template. +- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it. diff --git a/docs/workflows.ci.md b/docs/workflows.ci.md new file mode 100644 index 0000000..da01955 --- /dev/null +++ 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 new file mode 100644 index 0000000..1541c04 --- /dev/null +++ b/docs/workflows.md @@ -0,0 +1,14 @@ +# 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. +- [**Secrets Management**](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions. +- [**Workflow Scheduling**](./workflows.scheduling.md) - Automating recurring tasks with cron. diff --git a/docs/workflows.pages.md b/docs/workflows.pages.md new file mode 100644 index 0000000..edb58bc --- /dev/null +++ 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 new file mode 100644 index 0000000..2d92715 --- /dev/null +++ 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 new file mode 100644 index 0000000..127c1e0 --- /dev/null +++ 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/workflows.scheduling.md b/docs/workflows.scheduling.md new file mode 100644 index 0000000..f891436 --- /dev/null +++ b/docs/workflows.scheduling.md @@ -0,0 +1,108 @@ +# Scheduling Workflows with Cron + +GitHub Actions allows you to automate tasks on a schedule, similar to the +traditional cron utility in Unix-like systems. +This is useful for recurring tasks like nightly builds, daily reports, or +weekly dependency checks. + +## How it Works + +You can trigger a workflow to run at specific UTC times using the `schedule` +event. +This event is configured with a `cron` expression. + +```yaml +on: + schedule: + - cron: "30 5 * * 1-5" +``` + +This example triggers the workflow at 5:30 AM UTC every day from Monday to +Friday. + +## Understanding Cron Syntax + +A cron expression is a string of five fields that represent a time schedule. + +``` +┌───────────── minute (0 - 59) +│ ┌───────────── hour (0 - 23) +│ │ ┌───────────── day of the month (1 - 31) +│ │ │ ┌───────────── month (1 - 12) +│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday) +│ │ │ │ │ +│ │ │ │ │ +* * * * * +``` + +### Special Characters + +- `*`: Matches any value. + `* * * * *` runs every minute. +- `,`: Separates multiple values. + `0,15,30,45 * * * *` runs at minutes 0, 15, 30, and 45. +- `-`: Defines a range of values. + `0 9-17 * * *` runs every hour from 9 AM to 5 PM. +- `/`: Specifies a step value. + `*/15 * * * *` runs every 15 minutes. + +### Examples + +| Cron Expression | Description | +| ----------------- | -------------------------------------------------- | +| `0 0 * * *` | Run at midnight UTC every day. | +| `0 9 * * 1` | Run at 9:00 AM UTC every Monday. | +| `0 * * * *` | Run at the beginning of every hour. | +| `*/30 9-17 * * *` | Run every 30 minutes between 9 AM and 5 PM UTC. | +| `0 0 1 * *` | Run at midnight UTC on the first day of the month. | + +## Example Workflow + +Here is a complete example of a workflow that runs a script every day at +midnight UTC. + +```yaml +# .github/workflows/nightly-build.yml +name: Nightly Build + +on: + schedule: + - cron: "0 0 * * *" + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v3 + + - name: Run nightly script + run: ./scripts/run-nightly.sh +``` + +## Best Practices + +1. **Use UTC:** All scheduled times are in Coordinated Universal Time (UTC). + Be sure to account for time zone differences. + +2. **Minimum Frequency:** The shortest interval you can schedule a workflow to + run is every 5 minutes. + +3. **Use `workflow_dispatch`:** It's a good practice to add + `workflow_dispatch` alongside `schedule`. + This allows you to manually trigger the workflow from the GitHub UI, which + is very useful for testing. + +4. **Be Mindful of Usage:** Scheduled workflows consume your GitHub Actions + minutes. + If a task doesn't need to run frequently, choose a longer interval. + +5. **Handle Failures:** Consider adding a step to your workflow to send a + notification (e.g., via email or Slack) if a scheduled job fails. + This way, you can quickly address any issues. + +By leveraging scheduled workflows, you can automate a wide range of +maintenance and operational tasks, helping to keep your project healthy and +up-to-date. diff --git a/docs/workflows.secrets-management.md b/docs/workflows.secrets-management.md new file mode 100644 index 0000000..531fd3e --- /dev/null +++ b/docs/workflows.secrets-management.md @@ -0,0 +1,78 @@ +# Secrets Management in GitHub Actions + +Properly managing secrets like API keys, access tokens, and other credentials +is a critical aspect of security. +This guide explains the best practice of using GitHub Actions secrets to handle +sensitive information. + +## Why Secret Management is Important + +**Never commit secrets directly to your repository.** +Once a secret is in your git history, it should be considered compromised, +even if you later remove it from the current version of the code. +A public repository is visible to everyone, and malicious actors actively +scan for exposed credentials. + +Leaked secrets can lead to: + +- Unauthorized access to your accounts and services. +- Financial loss (e.g., if an API key for a paid service is stolen). +- Damage to your project's reputation. + +## Using GitHub Actions Secrets + +GitHub provides a secure way to store and use secrets within your repository +for use in GitHub Actions workflows. + +### How it Works + +1. **Encrypted Storage:** Secrets are stored as encrypted values at the + repository or organization level. +2. **Limited Access:** Secrets are only exposed to the specific GitHub Actions + workflows you choose. + They are not accessible to collaborators or even the repository owner once + they are set. +3. **Redacted Logs:** GitHub automatically redacts secrets from workflow logs, + preventing them from being accidentally exposed in build outputs. + +### How to Add a Repository Secret + +1. Navigate to your repository on GitHub. +2. Go to **Settings** > **Secrets and variables** > **Actions**. +3. Click the **New repository secret** button. +4. Enter a name for your secret (e.g., `NPM_TOKEN`, `AWS_ACCESS_KEY_ID`). + This name will be used to reference the secret in your workflow files. +5. Paste the secret value into the **Value** field. +6. Click **Add secret**. + +![GitHub new secret page](https://docs.github.com/assets/cb-57155/images/help/repository/actions-secrets-tab.png) + +### How to Use a Secret in a Workflow + +Once a secret is stored, you can access it in your workflow `.yml` files using +the `secrets` context. + +Here's an example of a workflow step that uses a secret to publish a package +to the npm registry: + +```yaml +- name: Publish to npm + uses: actions/setup-node@v3 + with: + node-version: "18" + registry-url: "https://registry.npmjs.org" +- run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} +``` + +In this example: + +- `secrets.NPM_TOKEN` refers to a repository secret named `NPM_TOKEN`. +- The secret's value is assigned to the `NODE_AUTH_TOKEN` environment + variable, which is used by the `npm publish` command for authentication. + +By using GitHub Actions secrets, you can automate workflows that require access +to sensitive information without compromising on security. +It's a fundamental practice for any project that interacts with external +services. From be2f4685ebf7c783e15bb1430631e939be6b6301 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 6 Sep 2025 12:13:00 +0000 Subject: [PATCH 3/5] docs: implement dual-TOC structure and update guidelines - Restructures `docs/README.md` to be a master Table of Contents, linking to all individual documentation pages, grouped by namespace. - Adds a quick-link navigation bar to the top of `docs/README.md`. - Ensures `docs/.md` files serve as introductions and scoped TOCs for their respective namespaces. - Updates `AGENTS.md` to reflect the new dual-TOC documentation rules, instructing future agents to add links to both `README.md` and the relevant `namespace.md` file when adding new documentation. --- AGENTS.md | 6 +++-- docs/README.md | 71 +++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 63 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 24d5cad..204465c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,10 +89,12 @@ repository: - **Update Documentation:** If you change a feature, you **must** update its corresponding documentation in the [`docs/`](./docs/) directory. If you add a new feature, you **must** create a new documentation file for - it, following the namespace structure. This means: + it, following the namespace and dual-TOC structure. This means: 1. Identify the correct namespace for your documentation (e.g., `development`, `workflows`). 2. Create a new file named `docs/..md`. - 3. Add a link to your new file in the corresponding namespace index file (e.g., `docs/.md`). + 3. Add a link to your new file in **two** places: + - The main Table of Contents in `docs/README.md`, under the appropriate namespace heading. + - The namespace-specific index file, `docs/.md`. 4. If you are creating a new namespace, you must also create a `docs/.md` index file and link to it from the main `docs/README.md`. - **Verify Your Work:** After creating or modifying a file, use a read-only tool like `read_file` or `ls` to confirm your changes were applied diff --git a/docs/README.md b/docs/README.md index 7d7f2c6..3a2c1ae 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,15 +5,62 @@ This directory contains the documentation for the `base` project. - [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template. - [Documentation Index](./README.md) - You are here. -## Namespaces - -- [AI](./ai.md) - Documentation related to Artificial Intelligence. -- [CI/CD](./workflows.md) - Documentation for the CI/CD workflows. -- [Community](./community.md) - Documentation related to community management. -- [Deployment](./deployment.md) - Documentation related to deployment. -- [Development](./development.md) - Documentation related to development practices and environment setup. -- [Documentation](./documentation.md) - Documentation about writing documentation. -- [Guides](./guides.md) - Guides for using this project. -- [Project Management](./project.md) - Documentation related to project management. -- [Publishing](./publishing.md) - Documentation about publishing content. -- [Updating](./updating.md) - Documentation about updating the repository. +[AI](#ai) - [CI/CD](#cicd-workflows) - [Community](#community) - [Development](#development) - [Documentation](#documentation-best-practices) - [Guides](#guides) - [Project Management](#project-management) - [Publishing](#publishing-your-project) - [Updating](#updating) + +## AI + +- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents. +- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents. + +## CI/CD Workflows + +- [**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. +- [**Secrets Management**](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions. +- [**Workflow Scheduling**](./workflows.scheduling.md) - Automating recurring tasks with cron. + +## 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. + +## Development + +- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development. +- [Docker Environment](./development.docker.md) - Using the included Docker setup. +- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files. +- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier. +- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code. + +## Documentation Best Practices + +- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. + +## Guides + +- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. + +## Project Management + +- [Repository Badges](./project.badges.md) - How to use and create repository badges. +- [Launch Checklist](./project.launch-checklist.md) - A reusable checklist for project launches. +- [Licensing Info](./project.licensing.md) - Details on the MIT License. +- [Security Best Practices](./project.security.md) - Basic security practices for maintainers. +- [Standard Files](./project.standard-files.md) - Explanation of standard repo files. +- [Template Repo Guide](./project.template-repo.md) - Best practices for maintaining this template. +- [Versioning Guide](./project.versioning.md) - Professional release management. + +## Publishing Your Project + +- **[Publishing with Markdown](./publishing.markdown.md)** - This is the simplest way to get started. +- **[Advanced Publishing with HTML](./publishing.html.md)** - For those who need more control over their site's layout and appearance. +- **[Publishing with Magic Links](./publishing.magic-links.md)** - This guide explains a powerful feature for community-driven sites. +- **[GitHub Pages](./publishing.github-pages.md)** - This document provides more detail on how the underlying GitHub Pages service works. + +## Updating + +- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template. +- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it. From 8d2e27d4b84ea64a56506930592b16ea816322bc Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 6 Sep 2025 12:27:59 +0000 Subject: [PATCH 4/5] docs: reorder namespaces and finalize documentation structure - Reorders the namespaces in `docs/README.md` to follow a more logical, user-centric flow, from initial use to contribution and maintenance. - The new order is: Guides, Development, CI/CD, Publishing, Updating, Project Management, Community, AI, Documentation. - The quick-link navigation bar at the top of `docs/README.md` is also updated to reflect this new order. - This commit finalizes the documentation structure according to all the user's requirements. --- docs/README.md | 60 +++++++++++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3a2c1ae..2e145d6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,12 +5,19 @@ This directory contains the documentation for the `base` project. - [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template. - [Documentation Index](./README.md) - You are here. -[AI](#ai) - [CI/CD](#cicd-workflows) - [Community](#community) - [Development](#development) - [Documentation](#documentation-best-practices) - [Guides](#guides) - [Project Management](#project-management) - [Publishing](#publishing-your-project) - [Updating](#updating) +[Guides](#guides) - [Development](#development) - [CI/CD](#cicd-workflows) - [Publishing](#publishing-your-project) - [Updating](#updating) - [Project Management](#project-management) - [Community](#community) - [AI](#ai) - [Documentation](#documentation-best-practices) -## AI +## Guides -- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents. -- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents. +- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. + +## Development + +- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development. +- [Docker Environment](./development.docker.md) - Using the included Docker setup. +- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files. +- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier. +- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code. ## CI/CD Workflows @@ -21,27 +28,17 @@ This directory contains the documentation for the `base` project. - [**Secrets Management**](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions. - [**Workflow Scheduling**](./workflows.scheduling.md) - Automating recurring tasks with cron. -## 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. - -## Development - -- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development. -- [Docker Environment](./development.docker.md) - Using the included Docker setup. -- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files. -- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier. -- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code. - -## Documentation Best Practices +## Publishing Your Project -- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. +- **[Publishing with Markdown](./publishing.markdown.md)** - This is the simplest way to get started. +- **[Advanced Publishing with HTML](./publishing.html.md)** - For those who need more control over their site's layout and appearance. +- **[Publishing with Magic Links](./publishing.magic-links.md)** - This guide explains a powerful feature for community-driven sites. +- **[GitHub Pages](./publishing.github-pages.md)** - This document provides more detail on how the underlying GitHub Pages service works. -## Guides +## Updating -- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. +- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template. +- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it. ## Project Management @@ -53,14 +50,17 @@ This directory contains the documentation for the `base` project. - [Template Repo Guide](./project.template-repo.md) - Best practices for maintaining this template. - [Versioning Guide](./project.versioning.md) - Professional release management. -## Publishing Your Project +## Community -- **[Publishing with Markdown](./publishing.markdown.md)** - This is the simplest way to get started. -- **[Advanced Publishing with HTML](./publishing.html.md)** - For those who need more control over their site's layout and appearance. -- **[Publishing with Magic Links](./publishing.magic-links.md)** - This guide explains a powerful feature for community-driven sites. -- **[GitHub Pages](./publishing.github-pages.md)** - This document provides more detail on how the underlying GitHub Pages service works. +- [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. -## Updating +## AI -- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template. -- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it. +- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents. +- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents. + +## Documentation Best Practices + +- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. From e721bebac47c36de6613ec643eda507ba2f4a951 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 6 Sep 2025 14:33:48 +0000 Subject: [PATCH 5/5] docs: reorder namespaces and finalize documentation structure - Reorders the namespaces in `docs/README.md` to follow a more logical, user-centric flow, from initial use to contribution and maintenance. - The new order is: Guides, Development, CI/CD, Publishing, Updating, Project Management, Community, AI, Documentation. - The quick-link navigation bar at the top of `docs/README.md` is also updated to reflect this new order. - Removes the redundant 'Documentation Index' link from `docs/README.md`. - This commit finalizes the documentation structure according to all the user's requirements. --- docs/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 2e145d6..1079751 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,6 @@ This directory contains the documentation for the `base` project. - [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template. -- [Documentation Index](./README.md) - You are here. [Guides](#guides) - [Development](#development) - [CI/CD](#cicd-workflows) - [Publishing](#publishing-your-project) - [Updating](#updating) - [Project Management](#project-management) - [Community](#community) - [AI](#ai) - [Documentation](#documentation-best-practices)