From bd7f2d4370209ad9c4e8f7c13e947baf6a388de4 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 11:59:59 +0000 Subject: [PATCH] This commit updates a number of markdown files throughout the repository to use relative links for local files, instead of plain text. This improves the readability and navigability of the documentation. The following files were updated: - AGENTS.md - CONTRIBUTING.md - .github/PULL_REQUEST_TEMPLATE.md - .github/SECURITY.md - docs/docker.md - docs/github-codespaces.md - docs/github-workflows.md - docs/standard-files.md This work was done in response to a request to update all markdown files. The process is not yet complete, and there are still some markdown files that need to be checked for plain text file path references. The work was submitted at the user's request. --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/SECURITY.md | 2 +- AGENTS.md | 56 +++++++++++++++++--------------- CONTRIBUTING.md | 2 +- docs/docker.md | 12 +++---- docs/github-codespaces.md | 4 +-- docs/github-workflows.md | 10 +++--- docs/standard-files.md | 10 +++--- 8 files changed, 50 insertions(+), 48 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 265faa6..db73f57 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -11,7 +11,7 @@ If it fixes an open issue, please link to the issue. ### Checklist -- [ ] I have read the [CONTRIBUTING.md](CONTRIBUTING.md) document. +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) document. - [ ] My code follows the style guidelines of this project. - [ ] I have added tests that prove my fix is effective or that my feature works. - [ ] All new and existing tests passed. diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 6f6c8fe..0e861f7 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -1,6 +1,6 @@ # Security Policy -This is a template repository. To create a security policy for your own project based on this template, you should create your own `SECURITY.md` file. +This is a template repository. To create a security policy for your own project based on this template, you should create your own [`SECURITY.md`](../SECURITY.md) file. This file should contain information about which versions of your project are supported with security updates and, most importantly, how to report a vulnerability. diff --git a/AGENTS.md b/AGENTS.md index d94ea30..5e380d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,44 +7,46 @@ Hello, AI assistant! This file is your guide to understanding and working with t The `base` repository serves as a high-quality, professional, and language-agnostic template for creating new software projects. Its core principles are: 1. **Code-Independent:** The `base` template itself should not be tied to any specific programming language. The included Docker environment is based on Ubuntu and NGINX to be as generic as possible. -2. **Well-Documented:** Every feature, configuration file, and workflow should have corresponding documentation in the `/docs` directory. The goal is to leave no part of the repository unexplained. -3. **Guidance over Prescription:** For files like `CONTRIBUTING.md` or `LICENSE`, the template provides sensible defaults and guides the end-user on how to customize them, rather than enforcing a single choice. + +- **Well-Documented:** Every feature, configuration file, and workflow should have corresponding documentation in the [`/docs`](./docs) directory. The goal is to leave no part of the repository unexplained. +- **Guidance over Prescription:** For files like [`CONTRIBUTING.md`](./CONTRIBUTING.md) or [`LICENSE`](./LICENSE), the template provides sensible defaults and guides the end-user on how to customize them, rather than enforcing a single choice. + 4. **Automation:** The repository leverages GitHub Actions for CI, deployment, and releases to automate common developer tasks. ## Repository Structure This is a breakdown of the most important files and directories in this repository: -- **`.github/`**: Contains all GitHub-specific configurations. +- **[`.github/`](./.github/)**: Contains all GitHub-specific configurations. - `workflows/`: Houses the GitHub Actions workflows. - - `ci.yml`: Lints configuration files for syntax and style. - - `pages.yml`: Deploys the documentation to GitHub Pages. - - `release-on-tag.yml`: Automates the creation of GitHub Releases from a git tag. - - `ISSUE_TEMPLATE/` & `PULL_REQUEST_TEMPLATE.md`: Templates for contributors. - - `RELEASE_TITLE.txt` & `RELEASE_BODY.md`: User-editable files for customizing release notes. - - `SECURITY.md`: A template for the user's security policy. + - [`ci.yml`](./.github/workflows/ci.yml): Lints configuration files for syntax and style. + - [`pages.yml`](./.github/workflows/pages.yml): Deploys the documentation to GitHub Pages. + - [`release-on-tag.yml`](./.github/workflows/release-on-tag.yml): Automates the creation of GitHub Releases from a git tag. + - [`ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE/) & [`PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md): Templates for contributors. + - [`RELEASE_TITLE.txt`](./.github/RELEASE_TITLE.txt) & [`RELEASE_BODY.md`](./.github/RELEASE_BODY.md): User-editable files for customizing release notes. + - [`SECURITY.md`](./.github/SECURITY.md): A template for the user's security policy. -- **`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. Each major feature or component has its own corresponding `.md` file in this directory. -- **`docker/`**: Contains the development environment. - - `Dockerfile`: Builds a generic Ubuntu + NGINX environment. - - `nginx.conf` & `html/index.html`: A simple web server that acts as a health check. +- **[`docker/`](./docker/)**: Contains the development environment. + - [`Dockerfile`](./docker/Dockerfile): Builds a generic Ubuntu + NGINX environment. + - [`nginx.conf`](./docker/nginx.conf) & [`html/index.html`](./docker/html/index.html): A simple web server that acts as a health check. -- **`.devcontainer/`**: Configuration for GitHub Codespaces, making it easy to spin up the development environment in the cloud. +- **[`.devcontainer/`](./.devcontainer/)**: Configuration for GitHub Codespaces, making it easy to spin up the development environment in the cloud. - **Root Files**: - - `AGENTS.md`: This file! - - `README.md`: The main entry point, which links to the documentation. - - `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `LICENSE`: Standard community files, designed as templates for the end-user. - - `.gitignore`, `.editorconfig`, `.gitattributes`, `.prettierrc`: Configuration files for git and code styling. - - `docker-compose.yml`: Used to build and run the Docker-based development environment. - - `render.yaml`: Infrastructure-as-code for deploying the application to Render.com. - - `_config.yml`: Configuration for the Jekyll build for GitHub Pages. + - [`AGENTS.md`](./AGENTS.md): This file! + - [`README.md`](./README.md): The main entry point, which links to the documentation. + - [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md), [`LICENSE`](./LICENSE): Standard community files, designed as templates for the end-user. + - [`.gitignore`](./.gitignore), [`.editorconfig`](./.editorconfig), [`.gitattributes`](./.gitattributes), [`.prettierrc`](./.prettierrc): Configuration files for git and code styling. + - [`docker-compose.yml`](./docker-compose.yml): Used to build and run the Docker-based development environment. + - [`render.yaml`](./render.yaml): Infrastructure-as-code for deploying the application to Render.com. + - [`_config.yml`](./_config.yml): Configuration for the Jekyll build for GitHub Pages. ## Guidelines for Modification - **Maintain the Philosophy:** When adding or changing features, always adhere to the core principles, especially being code-independent. -- **Update Documentation:** If you change a feature, you **must** update its corresponding documentation in the `docs/` directory. If you add a new feature, you **must** create a new documentation file for it. +- **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. - **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. Thank you for your help in maintaining and improving this repository! @@ -55,19 +57,19 @@ As an advanced AI assistant, you have a unique responsibility to uphold the qual ### 1. Onboarding & Planning -- **Initial Read-Through:** Always start by reading this file (`AGENTS.md`) and the main `README.md` in their entirety. -- **Documentation-First Planning:** Your plan **must** include steps for updating or creating documentation. For any change to a feature, identify and list the corresponding documentation file in `docs/` that you will update. For a new feature, your plan must include a step to create a new, well-named file in `docs/`. +- **Initial Read-Through:** Always start by reading this file ([`AGENTS.md`](./AGENTS.md)) and the main [`README.md`](./README.md) in their entirety. +- **Documentation-First Planning:** Your plan **must** include steps for updating or creating documentation. For any change to a feature, identify and list the corresponding documentation file in [`docs/`](./docs) that you will update. For a new feature, your plan must include a step to create a new, well-named file in `docs/`. ### 2. Upholding Core Philosophy - **Code-Independence:** If a user asks you to add language-specific code (e.g., Python, JavaScript), you must first ask for clarification. Confirm if they intend to make the repository language-specific, as this is a deviation from the core philosophy. Propose language-agnostic solutions where possible (e.g., shell scripts, Docker configurations, GitHub Actions). -- **Automation:** When adding or modifying workflows in `.github/workflows/`, ensure your changes are robust and well-documented with comments within the YAML file itself. +- **Automation:** When adding or modifying workflows in [`.github/workflows/`](./.github/workflows/), ensure your changes are robust and well-documented with comments within the YAML file itself. ### 3. Verification & Testing -- **Use the CI:** This repository has a `ci.yml` workflow that lints common configuration files. If you modify files like `docker-compose.yml` or GitHub Actions workflows, your plan should include a step to observe the CI run and ensure it passes. +- **Use the CI:** This repository has a [`ci.yml`](./.github/workflows/ci.yml) workflow that lints common configuration files. If you modify files like [`docker-compose.yml`](./docker-compose.yml) or GitHub Actions workflows, your plan should include a step to observe the CI run and ensure it passes. - **Targeted Testing:** Since the repository is language-agnostic, your testing approach must be specific to the changes you make. - - **Docker Changes:** If you modify `docker/Dockerfile` or `docker-compose.yml`, a step in your plan must be to run `docker-compose build` to ensure it builds successfully. + - **Docker Changes:** If you modify [`docker/Dockerfile`](./docker/Dockerfile) or [`docker-compose.yml`](./docker-compose.yml), a step in your plan must be to run `docker-compose build` to ensure it builds successfully. - **GitHub Actions:** If you change a workflow file, your verification should involve checking the "Actions" tab on the repository to confirm the run was successful. ### 4. Submitting Your Work diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5f6775..389cb2f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ This repository is a template. The contribution guide below is a generic placeho ## Getting Started -- Ensure you have read the project's `README.md`. +- Ensure you have read the project's [`README.md`](./README.md). - If you are proposing a new feature, open an issue first to discuss it. ## Making Changes diff --git a/docs/docker.md b/docs/docker.md index 8a35ef0..3d7cd9d 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -6,11 +6,11 @@ This repository includes a Docker-based development environment to ensure a cons The environment is defined by several files: -- **`docker/Dockerfile`**: This is the blueprint for our development image. It starts from a standard Ubuntu 22.04 base, then installs NGINX and a set of common, language-agnostic development tools (`git`, `curl`, `build-essential`, etc.). -- **`docker/nginx.conf`**: This is a standard configuration file for the NGINX web server. It's set up to serve the content of the `docker/html` directory. -- **`docker/html/index.html`**: This simple file contains the word `pong` and is served by NGINX. It provides a simple way to check if the environment is running correctly (a "health check"). -- **`docker-compose.yml`**: This file makes it easy to build and run the development environment. It defines a single service named `dev` and maps port 80 inside the container to port 8080 on your local machine. -- **`.dockerignore`**: This file tells Docker which files and directories to exclude from the build context, which helps to speed up the image build process. +- **[`docker/Dockerfile`](../docker/Dockerfile)**: This is the blueprint for our development image. It starts from a standard Ubuntu 22.04 base, then installs NGINX and a set of common, language-agnostic development tools (`git`, `curl`, `build-essential`, etc.). +- **[`docker/nginx.conf`](../docker/nginx.conf)**: This is a standard configuration file for the NGINX web server. It's set up to serve the content of the `docker/html` directory. +- **[`docker/html/index.html`](../docker/html/index.html)**: This simple file contains the word `pong` and is served by NGINX. It provides a simple way to check if the environment is running correctly (a "health check"). +- **[`docker-compose.yml`](../docker-compose.yml)**: This file makes it easy to build and run the development environment. It defines a single service named `dev` and maps port 80 inside the container to port 8080 on your local machine. +- **[`.dockerignore`](../.dockerignore)**: This file tells Docker which files and directories to exclude from the build context, which helps to speed up the image build process. ## Getting Started @@ -45,7 +45,7 @@ To use the development environment, you must have [Docker](https://www.docker.co ## Extending the Environment -You can easily extend this environment by modifying the `docker/Dockerfile`. For example, to install Python, you could add the following line: +You can easily extend this environment by modifying the [`docker/Dockerfile`](../docker/Dockerfile). For example, to install Python, you could add the following line: ```Dockerfile RUN apt-get update && apt-get install -y python3 python3-pip diff --git a/docs/github-codespaces.md b/docs/github-codespaces.md index ee29b97..0be613f 100644 --- a/docs/github-codespaces.md +++ b/docs/github-codespaces.md @@ -4,9 +4,9 @@ This repository is configured to use [GitHub Codespaces](https://github.com/feat ## How It Works -The configuration is defined in the `.devcontainer/devcontainer.json` file. This file instructs GitHub Codespaces to: +The configuration is defined in the [`.devcontainer/devcontainer.json`](../.devcontainer/devcontainer.json) file. This file instructs GitHub Codespaces to: -1. **Use the Docker Environment:** It references our `docker-compose.yml` file to spin up the same development environment that you would use locally. +1. **Use the Docker Environment:** It references our [`docker-compose.yml`](../docker-compose.yml) file to spin up the same development environment that you would use locally. 2. **Install VS Code Extensions:** It automatically installs a few recommended Visual Studio Code extensions (Docker and GitLens) to enhance the development experience. ## Getting Started diff --git a/docs/github-workflows.md b/docs/github-workflows.md index 5d97f72..dbfbfb6 100644 --- a/docs/github-workflows.md +++ b/docs/github-workflows.md @@ -2,22 +2,22 @@ This document explains the purpose and usage of the GitHub Actions workflows included in this repository. -## `ci.yml` +## [`ci.yml`](../.github/workflows/ci.yml) - **Purpose:** This workflow runs on every push and pull request to the `main` branch. It uses [Prettier](https://prettier.io/) to check for consistent formatting in Markdown and YAML files, ensuring code quality and readability. - **Triggers:** `push`, `pull_request` to `main`. -## `pages.yml` +## [`pages.yml`](../.github/workflows/pages.yml) -- **Purpose:** This workflow builds and deploys the project's documentation as a GitHub Pages website. It uses the root `README.md` as the homepage. +- **Purpose:** This workflow builds and deploys the project's documentation as a GitHub Pages website. It uses the root [`README.md`](../README.md) as the homepage. - **Triggers:** `push` to `main`, `workflow_dispatch`. -## `release-on-tag.yml` +## [`release-on-tag.yml`](../.github/workflows/release-on-tag.yml) - **Purpose:** This workflow automates the creation of GitHub Releases. - **Triggers:** `push` of a new tag matching the pattern `v*.*.*`. - **Usage:** - 1. Edit the `.github/RELEASE_TITLE.txt` and `.github/RELEASE_BODY.md` files to describe the release. You can use the `${TAG}` variable. + 1. Edit the [`.github/RELEASE_TITLE.txt`](../.github/RELEASE_TITLE.txt) and [`.github/RELEASE_BODY.md`](../.github/RELEASE_BODY.md) files to describe the release. You can use the `${TAG}` variable. 2. Commit these changes. 3. Push a new tag (e.g., `git tag v1.0.0 && git push origin v1.0.0`). 4. The workflow will automatically create a new release with your notes, a full changelog, and a link to the diff. diff --git a/docs/standard-files.md b/docs/standard-files.md index e4217a1..c4d0746 100644 --- a/docs/standard-files.md +++ b/docs/standard-files.md @@ -2,26 +2,26 @@ This document explains the purpose of the standard, language-agnostic configuration files included in this repository. -## `.gitignore` +## [`.gitignore`](../.gitignore) This file tells the `git` version control system which files and directories to ignore. The one included in this repository is pre-populated with common ignores for operating system files (like `.DS_Store` on macOS) and IDE configuration folders (like `.vscode`). [Learn more about `.gitignore`](https://git-scm.com/docs/gitignore). -## `.editorconfig` +## [`.editorconfig`](../.editorconfig) This file helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. The included file sets basic standards like using spaces for indentation and trimming trailing whitespace. [Learn more about EditorConfig](https://editorconfig.org/). -## `.gitattributes` +## [`.gitattributes`](../.gitattributes) This file is used to define attributes per path. The included file has a single, important rule: `* text=auto eol=lf`. This enforces consistent line endings (LF) for all text files, which prevents common issues when developers use different operating systems. [Learn more about `.gitattributes`](https://git-scm.com/docs/gitattributes). -## `.prettierrc` +## [`.prettierrc`](../.prettierrc) -This file configures the [Prettier](https://prettier.io/) code formatter. Prettier is used in the `ci.yml` workflow to ensure that all Markdown and YAML files in the repository have a consistent style. +This file configures the [Prettier](https://prettier.io/) code formatter. Prettier is used in the [`ci.yml`](../.github/workflows/ci.yml) workflow to ensure that all Markdown and YAML files in the repository have a consistent style. [Learn more about Prettier configuration](https://prettier.io/docs/en/configuration.html).