From 17a429d533203d1954015156d9fcccab8a3222e9 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 5 Sep 2025 09:22:35 +0000 Subject: [PATCH 1/3] Refactor documentation for updating and merging base This commit refactors the documentation for updating and merging `base`. - Creates two new guides for the two different scenarios of merging and updating. - Renames the guide files to be more descriptive. - Creates a new "Updating" section in the documentation index. - Corrects the git commands in the guides to be accurate for each scenario. --- docs/README.md | 6 +- docs/development.merging-base.md | 103 ------------ docs/updating.adding-base-to-existing-repo.md | 143 ++++++++++++++++ ....syncing-your-repo-when-base-is-updated.md | 154 ++++++++++++++++++ 4 files changed, 302 insertions(+), 104 deletions(-) delete mode 100644 docs/development.merging-base.md create mode 100644 docs/updating.adding-base-to-existing-repo.md create mode 100644 docs/updating.syncing-your-repo-when-base-is-updated.md diff --git a/docs/README.md b/docs/README.md index 58eb1c2..0c9e5f2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,7 +30,6 @@ This directory contains the documentation for the `base` project. - [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development. - [Docker Environment](./development.docker.md) - Using the included Docker setup. -- [Merging `base`](./development.merging-base.md) - Incorporating `base` into an existing project. - [`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. @@ -43,6 +42,11 @@ This directory contains the documentation for the `base` project. - [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. diff --git a/docs/development.merging-base.md b/docs/development.merging-base.md deleted file mode 100644 index a42086e..0000000 --- a/docs/development.merging-base.md +++ /dev/null @@ -1,103 +0,0 @@ -# Merging `base` Into an Existing Repository - -This guide explains how to merge the `attogram/base` repository into your existing project. This is useful for incorporating the `base` features, such as the Docker environment and GitHub Actions, into a project that has already been started. - -There are two ways to do this: an easy method using the GitHub web interface, and an advanced method using the command line on your local machine. - ---- - -## Easy Method: Using GitHub Codespaces (Web-Based) - -This method is recommended if you are not familiar with the command line or do not have Git installed on your machine. It uses GitHub Codespaces, which provides a development environment that runs in your browser. - -1. **Navigate to Your Repository:** - Go to the main page of your own existing repository on GitHub. - -2. **Launch a New Codespace:** - - Click the **"<> Code"** button. - - Go to the **"Codespaces"** tab. - - Click **"Create codespace on [your-branch-name]"**. This will create a new development environment and open it in a new browser tab. - -3. **Open the Terminal:** - Once the Codespace has loaded, you will see a code editor and a file browser. You need to open the terminal: - - Click the "hamburger" menu (☰) in the top-left corner. - - Go to **"Terminal" > "New Terminal"**. - -4. **Run the Merge Commands:** - In the terminal, you will now run a series of Git commands. These are the same commands as the advanced method, but you are running them in the browser instead of on your local machine. - - **Add `base` as a remote:** This tells Git where to find the `attogram/base` repository. - ```bash - git remote add base https://github.com/attogram/base.git - ``` - - **Fetch and merge `base`:** This downloads the `base` repository and merges it into your project. - ```bash - git fetch base - git merge base/main --allow-unrelated-histories - ``` - -5. **Handle Merge Conflicts:** - If there are any merge conflicts, the Codespace will highlight the affected files in the file browser. - - Click on a conflicted file to open it. - - The editor will show you the conflicting changes with markers (`<<<<<<<`, `=======`, `>>>>>>>`). - - You can use the buttons provided by the editor (**"Accept Current Change"**, **"Accept Incoming Change"**, etc.) to resolve the conflicts. - - Once you have resolved the conflicts in a file, save it. - -6. **Commit and Push the Changes:** - - Go to the **"Source Control"** tab on the left-hand side (it looks like a branching icon). - - Enter a commit message (e.g., "Merge attogram/base"). - - Click the checkmark icon to commit the changes. - - Click the **"Sync Changes"** button to push the changes to your repository on GitHub. - -7. **Create a Pull Request:** - - Go back to your repository's main page on GitHub. - - You will see a notification to create a Pull Request from your recently pushed changes. Click on it, review the details, and create the PR. - ---- - -## Advanced Method: Using the Command Line - -This method is for users who are comfortable with the command line and have Git installed on their local machine. - -### 1. Add `base` as a Remote - -First, you need to add the `base` repository as a remote to your local Git repository. This allows you to fetch its branches and history. - -Open your terminal, navigate to your project's root directory, and run the following command: - -```bash -git remote add base https://github.com/attogram/base.git -``` - -### 2. Fetch and Merge `base` - -Next, fetch the `base` repository's history and merge its `main` branch into your project's main branch. - -```bash -git fetch base -git merge base/main --allow-unrelated-histories -``` - -### 3. Handle Merge Conflicts - -It is highly likely that you will encounter merge conflicts. To resolve them: - -1. **Identify Conflicting Files:** Run `git status` to see a list of files with conflicts. -2. **Open the Files:** Open each conflicting file in your code editor and resolve the conflicts by editing the file and removing the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`). -3. **Stage the Resolved Files:** After resolving the conflicts, stage the files using `git add`. - ```bash - git add . - ``` -4. **Commit the Merge:** Once all conflicts are resolved, commit the merge. - ```bash - git commit - ``` - -### 4. Create a Pull Request - -After the merge is complete, push the changes to your repository and create a Pull Request. - -1. **Push Your Branch:** - ```bash - git push origin your-branch-name - ``` -2. **Open a Pull Request:** Go to your repository on GitHub. You will see a prompt to create a new Pull Request. Click on it, fill out the details, and create the PR. diff --git a/docs/updating.adding-base-to-existing-repo.md b/docs/updating.adding-base-to-existing-repo.md new file mode 100644 index 0000000..9d7145c --- /dev/null +++ b/docs/updating.adding-base-to-existing-repo.md @@ -0,0 +1,143 @@ +# Merging `base` Into an Existing Repository + +This guide explains how to merge the `attogram/base` repository into your +existing project. +This is useful for incorporating the `base` features, such as the Docker +environment and GitHub Actions, into a project that has already been started. + +There are two ways to do this: an easy method using the GitHub web interface, +and an advanced method using the command line on your local machine. + +--- + +## Initial Merge + +This section explains how to perform the first merge of `base` into your +repository. + +### Easy Method: Using GitHub Codespaces (Web-Based) + +This method is recommended if you are not familiar with the command line or do +not have Git installed on your machine. +It uses GitHub Codespaces, which provides a development environment that runs +in your browser. + +1. **Navigate to Your Repository:** + Go to the main page of your own existing repository on GitHub. + +2. **Launch a New Codespace:** + - Click the "**<> Code**" button. + - Go to the "**Codespaces**" tab. + - Click "**Create codespace on [your-branch-name]**". + This will create a new development environment and open it in a new browser + tab. + +3. **Open the Terminal:** + Once the Codespace has loaded, you will see a code editor and a file + browser. + You need to open the terminal: + - Click the "hamburger" menu (☰) in the top-left corner. + - Go to "**Terminal**" > "**New Terminal**". + +4. **Run the Merge Commands:** + In the terminal, you will now run a series of Git commands. + These are the same commands as the advanced method, but you are running them + in the browser instead of on your local machine. + - **Add `base` as a remote:** This tells Git where to find the + `attogram/base` repository. + ```bash + git remote add base https://github.com/attogram/base.git + ``` + - **Fetch and merge `base`:** This downloads the `base` repository and + merges it into your project. + ```bash + git fetch base + git merge base/main --allow-unrelated-histories + ``` + +5. **Handle Merge Conflicts:** + If there are any merge conflicts, the Codespace will highlight the affected + files in the file browser. + - Click on a conflicted file to open it. + - The editor will show you the conflicting changes with markers (`<<<<<<<`, + `=======`, `>>>>>>>`). + - You can use the buttons provided by the editor ("**Accept Current + Change**", "**Accept Incoming Change**", etc.) to resolve the conflicts. + - Once you have resolved the conflicts in a file, save it. + +6. **Commit and Push the Changes:** + - Go to the "**Source Control**" tab on the left-hand side (it looks like a + branching icon). + - Enter a commit message (e.g., "Merge attogram/base"). + - Click the checkmark icon to commit the changes. + - Click the "**Sync Changes**" button to push the changes to your + repository on GitHub. + +7. **Create a Pull Request:** + - Go back to your repository's main page on GitHub. + - You will see a notification to create a Pull Request from your recently + pushed changes. + - Click on it, review the details, and create the PR. + +### Advanced Method: Using the Command Line + +This method is for users who are comfortable with the command line and have Git +installed on their local machine. + +1. **Add `base` as a Remote:** + First, you need to add the `base` repository as a remote to your local Git + repository. + This allows you to fetch its branches and history. + ```bash + git remote add base https://github.com/attogram/base.git + ``` + +2. **Fetch and Merge `base`:** + Next, fetch the `base` repository's history and merge its `main` branch + into your project's main branch. + ```bash + git fetch base + git merge base/main --allow-unrelated-histories + ``` + +3. **Handle Merge Conflicts:** + It is highly likely that you will encounter merge conflicts. + To resolve them: + - Run `git status` to see a list of files with conflicts. + - Open each conflicting file in your code editor and resolve the conflicts. + - Stage the resolved files using `git add .`. + - Commit the merge with `git commit`. + +4. **Create a Pull Request:** + After the merge is complete, push the changes to your repository and create + a Pull Request. + +--- + +## Keeping Your Repository Updated + +After the initial merge, you can pull in future updates from `base` by running +the following commands: + +```bash +git fetch base +git merge base/main +``` + +You may need to resolve merge conflicts again, just as you did during the +initial merge. + +--- + +## Alternative: Copying Files + +If you only want to incorporate a small part of the `base` repository, like a +specific workflow or configuration file, you can simply copy and paste it into +your own project. + +For example, you can copy the contents of the +[`.github/`](https://github.com/attogram/base/tree/main/.github) directory to +get the latest GitHub Actions workflows. + +This method is simpler than a full merge, but you will need to manually update +the files if you want to get future updates from `base`. diff --git a/docs/updating.syncing-your-repo-when-base-is-updated.md b/docs/updating.syncing-your-repo-when-base-is-updated.md new file mode 100644 index 0000000..49ba137 --- /dev/null +++ b/docs/updating.syncing-your-repo-when-base-is-updated.md @@ -0,0 +1,154 @@ +# Syncing Your Repo When `base` is Updated + +This guide explains how to sync your repository with the latest changes from the +`attogram/base` template repository. +This is for repositories that were created using the "Use this template" button +on GitHub. + +This process assumes that you have not previously added the `base` repository +as a remote. If you have, you can skip to the `fetch` and `merge` steps. + +There are two ways to do this: an easy method using the GitHub web interface, +and an advanced method using the command line on your local machine. + +--- + +## Easy Method: Using GitHub Codespaces (Web-Based) + +This method is recommended if you are not familiar with the command line or do +not have Git installed on your machine. +It uses GitHub Codespaces, which provides a development environment that runs +in your browser. + +1. **Navigate to Your Repository:** + Go to the main page of your own existing repository on GitHub. + +2. **Launch a New Codespace:** + - Click the "**<> Code**" button. + - Go to the "**Codespaces**" tab. + - Click "**Create codespace on [your-branch-name]**". + This will create a new development environment and open it in a new browser + tab. + +3. **Open the Terminal:** + Once the Codespace has loaded, you will see a code editor and a file + browser. + You need to open the terminal: + - Click the "hamburger" menu (☰) in the top-left corner. + - Go to "**Terminal**" > "**New Terminal**". + +4. **Run the Sync Commands:** + In the terminal, you will now run a series of Git commands. + - **Add `base` as a remote (if you haven't already):** + This tells Git where to find the `attogram/base` repository. + ```bash + git remote add base https://github.com/attogram/base.git + ``` + - **Fetch and merge `base`:** + This downloads the `base` repository and merges it into your project. + ```bash + git fetch base + git merge base/main + ``` + +5. **Handle Merge Conflicts:** + If there are any merge conflicts, the Codespace will highlight the affected + files in the file browser. + - Click on a conflicted file to open it. + - The editor will show you the conflicting changes with markers (`<<<<<<<`, + `=======`, `>>>>>>>`). + - You can use the buttons provided by the editor ("**Accept Current + Change**", "**Accept Incoming Change**", etc.) to resolve the conflicts. + - Once you have resolved the conflicts in a file, save it. + +6. **Commit and Push the Changes:** + - Go to the "**Source Control**" tab on the left-hand side (it looks like a + branching icon). + - Enter a commit message (e.g., "Sync with attogram/base"). + - Click the checkmark icon to commit the changes. + - Click the "**Sync Changes**" button to push the changes to your repository + on GitHub. + +7. **Create a Pull Request:** + - Go back to your repository's main page on GitHub. + - You will see a notification to create a Pull Request from your recently + pushed changes. + - Click on it, review the details, and create the PR. + +--- + +## Advanced Method: Using the Command Line + +This method is for users who are comfortable with the command line and have Git +installed on their local machine. + +### 1. Add `base` as a Remote (if you haven't already) + +First, you need to add the `base` repository as a remote to your local Git +repository. +This allows you to fetch its branches and history. + +Open your terminal, navigate to your project's root directory, and run the +following command: + +```bash +git remote add base https://github.com/attogram/base.git +``` + +### 2. Fetch and Merge `base` + +Next, fetch the `base` repository's history and merge its `main` branch into +your project's main branch. + +```bash +git fetch base +git merge base/main +``` + +### 3. Handle Merge Conflicts + +It is highly likely that you will encounter merge conflicts. +To resolve them: + +1. **Identify Conflicting Files:** Run `git status` to see a list of files + with conflicts. +2. **Open the Files:** Open each conflicting file in your code editor and + resolve the conflicts by editing the file and removing the conflict markers + (`<<<<<<<`, `=======`, `>>>>>>>`). +3. **Stage the Resolved Files:** After resolving the conflicts, stage the + files using `git add`. + ```bash + git add . + ``` +4. **Commit the Merge:** Once all conflicts are resolved, commit the merge. + ```bash + git commit + ``` + +### 4. Create a Pull Request + +After the merge is complete, push the changes to your repository and create a +Pull Request. + +1. **Push Your Branch:** + ```bash + git push origin your-branch-name + ``` +2. **Open a Pull Request:** Go to your repository on GitHub. + You will see a prompt to create a new Pull Request. + Click on it, fill out the details, and create the PR. + +--- + +## Alternative: Copying Files + +If you only want to incorporate a small part of the `base` repository, like a +specific workflow or configuration file, you can simply copy and paste it into +your own project. + +For example, you can copy the contents of the +[`.github/`](https://github.com/attogram/base/tree/main/.github) directory to +get the latest GitHub Actions workflows. + +This method is simpler than a full merge, but you will need to manually update +the files if you want to get future updates from `base`. From 6c6b5d89ab4ead24030ebf9face28da908427ff0 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 5 Sep 2025 10:30:49 +0000 Subject: [PATCH 2/3] Refactor documentation for updating and merging base This commit refactors the documentation for updating and merging `base`. - Creates two new guides for the two different scenarios of merging and updating. - Renames the guide files to be more descriptive. - Creates a new "Updating" section in the documentation index. - Corrects the git commands in the guides to be accurate for each scenario. --- AGENTS.md | 153 +++++++++++++++++++------- docs/ai.agents-md.md | 45 ++++++-- docs/ai.prompting.md | 80 ++++++++++---- docs/base.md | 29 ++++- docs/cicd.secrets-management.md | 42 +++++-- docs/cicd.workflow-scheduling.md | 50 ++++++--- docs/cicd.workflows.md | 20 +++- docs/community.building.md | 62 ++++++++--- docs/community.discussions.md | 68 ++++++++---- docs/community.issue-management.md | 70 ++++++++---- docs/community.wiki.md | 61 +++++++--- docs/deployment.render.md | 16 ++- docs/development.codespaces.md | 29 +++-- docs/development.docker.md | 48 ++++++-- docs/development.package-json.md | 42 +++++-- docs/development.prettier-workflow.md | 20 +++- docs/development.prettier.md | 30 +++-- docs/documentation.best-practices.md | 76 +++++++++---- docs/guides.software-project.md | 102 ++++++++++++----- docs/project.badges.md | 68 +++++++++--- docs/project.launch-checklist.md | 35 ++++-- docs/project.licensing.md | 26 ++++- docs/project.security.md | 71 +++++++++--- docs/project.standard-files.md | 24 +++- docs/project.template-repo.md | 36 ++++-- docs/project.versioning.md | 57 +++++++--- docs/publishing.github-pages.md | 48 +++++--- docs/publishing.html.md | 95 +++++++++++----- docs/publishing.magic-links.md | 55 ++++++--- docs/publishing.markdown.md | 54 ++++++--- docs/publishing.md | 24 +++- 31 files changed, 1204 insertions(+), 432 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5e380d3..eeacb65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,79 +1,154 @@ # AGENTS.md: A Guide for AI Assistants -Hello, AI assistant! This file is your guide to understanding and working with the `base` repository. Please read it carefully before making any changes. +Hello, AI assistant! +This file is your guide to understanding and working with the `base` +repository. +Please read it carefully before making any changes. ## Core Philosophy -The `base` repository serves as a high-quality, professional, and language-agnostic template for creating new software projects. Its core principles are: +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. +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. -- **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. +- **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. +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: +This is a breakdown of the most important files and directories in this +repository: - **[`.github/`](./.github/)**: Contains all GitHub-specific configurations. - `workflows/`: Houses the GitHub Actions workflows. - - [`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/`](./docs/)**: Contains all documentation for the project. Each major feature or component has its own corresponding `.md` file in this directory. + - [`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/`](./docs/)**: Contains all documentation for the project. + Each major feature or component has its own corresponding `.md` file in this + directory. - **[`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. + - [`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/`](./.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`](./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. + - [`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/`](./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. +- **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/`](./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! ## For Jules: Specific Instructions -As an advanced AI assistant, you have a unique responsibility to uphold the quality and philosophy of this repository. The following guidelines are tailored to you. +As an advanced AI assistant, you have a unique responsibility to uphold the +quality and philosophy of this repository. +The following guidelines are tailored to you. ### 1. Onboarding & Planning -- **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/`. +- **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/`](./.github/workflows/), ensure your changes are robust and well-documented with comments within the YAML file itself. +- **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/`](./.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`](./.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`](./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. +- **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`](./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 -- **Run Prettier:** Before requesting a review, run `npx prettier --write .` to ensure all files are formatted correctly. -- **Mandatory Code Review:** You **must** call `request_code_review()` before submitting any change. -- **Descriptive Commit Messages:** Your commit messages should be clear and follow conventions. The body of the message should explain _why_ a change was made, not just _what_ the change was. +- **Run Prettier:** Before requesting a review, run `npx prettier --write .` + to ensure all files are formatted correctly. +- **Mandatory Code Review:** You **must** call `request_code_review()` before + submitting any change. +- **Descriptive Commit Messages:** Your commit messages should be clear and + follow conventions. + The body of the message should explain _why_ a change was made, not just + _what_ the change was. diff --git a/docs/ai.agents-md.md b/docs/ai.agents-md.md index 0644c13..231389a 100644 --- a/docs/ai.agents-md.md +++ b/docs/ai.agents-md.md @@ -1,27 +1,48 @@ # Guiding AI with `AGENTS.md` -The `AGENTS.md` file is a special document within this repository designed to be a direct line of communication between you (the user) and any AI agent or assistant working on your project. Think of it as a set of permanent instructions or a "cheat sheet" for the AI. +The `AGENTS.md` file is a special document within this repository designed to +be a direct line of communication between you (the user) and any AI agent or +assistant working on your project. +Think of it as a set of permanent instructions or a "cheat sheet" for the AI. ## What is its Purpose? -While you can give an AI instructions in a prompt, those instructions are temporary and specific to that one conversation. The `AGENTS.md` file provides a persistent set of rules and guidelines that the AI can refer to at any time. +While you can give an AI instructions in a prompt, those instructions are +temporary and specific to that one conversation. +The `AGENTS.md` file provides a persistent set of rules and guidelines that +the AI can refer to at any time. This is particularly useful for establishing: - **Coding Standards:** "Always use tabs, not spaces." -- **Architectural Rules:** "All new components must be registered in the main application file." -- **Testing Requirements:** "Every new function must be accompanied by a unit test." -- **Repository-Specific Information:** "The `api/` directory is auto-generated, do not edit it directly." +- **Architectural Rules:** "All new components must be registered in the main + application file." +- **Testing Requirements:** "Every new function must be accompanied by a unit + test." +- **Repository-Specific Information:** "The `api/` directory is + auto-generated, do not edit it directly." ## How to Use and Modify It -The `AGENTS.md` file is written in simple Markdown. You can edit it just like any other text file. +The `AGENTS.md` file is written in simple Markdown. +You can edit it just like any other text file. ### Best Practices -1. **Be Clear and Direct:** Write instructions as if you are speaking directly to the AI. Use clear, unambiguous language. -2. **Use Markdown for Structure:** Use headings, bullet points, and code blocks to keep the document organized and easy for the AI to parse. -3. **Keep It Updated:** As your project evolves, so should your `AGENTS.md` file. If you change your architecture or coding standards, update the file to reflect those changes. -4. **Reference It in Your Prompts:** For best results, remind the AI to look for and follow the instructions in your `AGENTS.md` file as part of your initial prompt. The `prompting-ai-agents.md` guide provides examples of how to do this. - -By maintaining a well-structured `AGENTS.md` file, you can significantly improve the quality and consistency of the work done by AI agents on your project, reducing the need for corrections and rework. +1. **Be Clear and Direct:** Write instructions as if you are speaking + directly to the AI. + Use clear, unambiguous language. +2. **Use Markdown for Structure:** Use headings, bullet points, and code + blocks to keep the document organized and easy for the AI to parse. +3. **Keep It Updated:** As your project evolves, so should your `AGENTS.md` + file. + If you change your architecture or coding standards, update the file to + reflect those changes. +4. **Reference It in Your Prompts:** For best results, remind the AI to look + for and follow the instructions in your `AGENTS.md` file as part of your + initial prompt. + The `prompting-ai-agents.md` guide provides examples of how to do this. + +By maintaining a well-structured `AGENTS.md` file, you can significantly +improve the quality and consistency of the work done by AI agents on your +project, reducing the need for corrections and rework. diff --git a/docs/ai.prompting.md b/docs/ai.prompting.md index f84db28..2f92eed 100644 --- a/docs/ai.prompting.md +++ b/docs/ai.prompting.md @@ -1,51 +1,87 @@ # Prompting AI Agents for `attogram/base` Projects -When using AI agents to create or update a repository based on `attogram/base`, providing a clear, upfront context is the most effective way to get the results you want. This guide provides two distinct prompt examples to help you steer AI agents in the right direction, whether you want to build upon the `base` philosophy or intentionally modify it. +When using AI agents to create or update a repository based on +`attogram/base`, providing a clear, upfront context is the most effective way +to get the results you want. +This guide provides two distinct prompt examples to help you steer AI agents in +the right direction, whether you want to build upon the `base` philosophy or +intentionally modify it. --- ## Prompt 1: Using `base` As-Is -This prompt is ideal when you want to create a new project that adheres to the core, language-agnostic philosophy of the `attogram/base` template. +This prompt is ideal when you want to create a new project that adheres to the +core, language-agnostic philosophy of the `attogram/base` template. ### Example Prompt: Create a Personal Blog ``` -This project builds upon the attogram/base template. Please integrate the new website content without removing the core base repository files or structure. - -The main homepage for the site is `README.md`, and all new content should be linked from there. You can create new directories for your content as needed, but please do not modify the core `base` files and directories (such as `.github`, `docs`, `docker`, etc.). - -Please use the existing Jekyll setup for the site, which builds from the root directory. Do not install other static site generators like Eleventy. - -Finally, please look for and follow any instructions in an `AGENTS.md` file, as it may contain project-specific guidelines for AI agents. +This project builds upon the attogram/base template. +Please integrate the new website content without removing the core base +repository files or structure. + +The main homepage for the site is `README.md`, and all new content should be +linked from there. +You can create new directories for your content as needed, but please do not +modify the core `base` files and directories (such as `.github`, `docs`, +`docker`, etc.). + +Please use the existing Jekyll setup for the site, which builds from the root +directory. +Do not install other static site generators like Eleventy. + +Finally, please look for and follow any instructions in an `AGENTS.md` file, +as it may contain project-specific guidelines for AI agents. ``` --- ## Prompt 2: Modifying `base` for a New Technology -This prompt is for when you want to use `attogram/base` as a starting point but intend to introduce a specific programming language or framework. This example uses PHP and Laravel. +This prompt is for when you want to use `attogram/base` as a starting point +but intend to introduce a specific programming language or framework. +This example uses PHP and Laravel. ### Example Prompt: Add a Laravel Backend ``` -This project will use `attogram/base` as a foundation, but we will be modifying it to support a PHP/Laravel application. +This project will use `attogram/base` as a foundation, but we will be +modifying it to support a PHP/Laravel application. Here are the requirements: -1. **Add PHP and Laravel:** Please modify the Docker environment to include PHP and the necessary extensions for a Laravel application. -2. **Install Laravel:** Once the environment is updated, install a fresh copy of the Laravel framework in a `/src` directory at the repository root. -3. **Update NGINX:** Configure the NGINX server to point to the `public` directory of the Laravel application. -4. **Preserve Core Files:** Do not remove the existing GitHub Actions workflows or the documentation in the `/docs` directory. The goal is to integrate Laravel into the `base` template, not replace it. -5. **Check for `AGENTS.md`:** Please look for and follow any instructions in an `AGENTS.md` file, as it may contain project-specific guidelines for AI agents. +1. **Add PHP and Laravel:** Please modify the Docker environment to include + PHP and the necessary extensions for a Laravel application. +2. **Install Laravel:** Once the environment is updated, install a fresh copy + of the Laravel framework in a `/src` directory at the repository root. +3. **Update NGINX:** Configure the NGINX server to point to the `public` + directory of the Laravel application. +4. **Preserve Core Files:** Do not remove the existing GitHub Actions + workflows or the documentation in the `/docs` directory. + The goal is to integrate Laravel into the `base` template, not replace it. +5. **Check for `AGENTS.md`:** Please look for and follow any instructions in + an `AGENTS.md` file, as it may contain project-specific guidelines for AI + agents. ``` --- ## Why These Prompts Work -Providing a detailed, upfront prompt like the examples above is crucial for several reasons: - -- **Sets Clear Expectations:** The AI immediately understands the scope of the project. It knows whether to preserve the `base` philosophy or to modify it, which is the most critical distinction. -- **Reduces Errors and Rework:** By specifying the technology stack (or lack thereof) and the desired file structure, you prevent the AI from making incorrect assumptions that would need to be corrected later. -- **Empowers the AI:** A clear prompt gives the AI the constraints it needs to be creative and effective. It can focus on the "how" because you've already defined the "what" and "why." -- **Faster, Better Results:** Ultimately, a few minutes spent crafting a detailed prompt will save you hours of back-and-forth, leading to a better final product that meets your requirements from the start. +Providing a detailed, upfront prompt like the examples above is crucial for +several reasons: + +- **Sets Clear Expectations:** The AI immediately understands the scope of the + project. + It knows whether to preserve the `base` philosophy or to modify it, which is + the most critical distinction. +- **Reduces Errors and Rework:** By specifying the technology stack (or lack + thereof) and the desired file structure, you prevent the AI from making + incorrect assumptions that would need to be corrected later. +- **Empowers the AI:** A clear prompt gives the AI the constraints it needs to + be creative and effective. + It can focus on the "how" because you've already defined the "what" and + "why." +- **Faster, Better Results:** Ultimately, a few minutes spent crafting a + detailed prompt will save you hours of back-and-forth, leading to a better + final product that meets your requirements from the start. diff --git a/docs/base.md b/docs/base.md index b6b71de..8ee6885 100644 --- a/docs/base.md +++ b/docs/base.md @@ -1,19 +1,36 @@ # The `base` Philosophy -Welcome to `base`. This repository is designed to be a robust, professional, and [well-documented](./README.md) starting point for new software and publishing projects. +Welcome to `base`. +This repository is designed to be a robust, professional, and +[well-documented](./README.md) starting point for new software and publishing +projects. ## Core Principles The development of this template is guided by a few core principles: -1. **Code-Independent:** The template should not be tied to a specific programming language. The goal is to provide a solid foundation of repository structure, CI/CD, and best practices that can be adapted to any language or framework. +1. **Code-Independent:** The template should not be tied to a specific + programming language. + The goal is to provide a solid foundation of repository structure, CI/CD, + and best practices that can be adapted to any language or framework. -2. **Well-Documented:** Every component, workflow, and configuration file is documented in the [`docs`](./) directory. The goal is to make the repository easy to understand and modify. See the [documentation index](./README.md) for a complete list of documents. +2. **Well-Documented:** Every component, workflow, and configuration file is + documented in the [`docs`](./) directory. + The goal is to make the repository easy to understand and modify. + See the [documentation index](./README.md) for a complete list of + documents. -3. **Guidance Over Prescription:** The template provides sensible defaults and placeholder files that guide the user on how to create their own project-specific content, such as contributing guidelines or a license. +3. **Guidance Over Prescription:** The template provides sensible defaults and + placeholder files that guide the user on how to create their own + project-specific content, such as contributing guidelines or a license. -4. **Automation:** The template includes automated workflows for common tasks like linting, testing, and creating releases, helping to ensure code quality and streamline the development process. +4. **Automation:** The template includes automated workflows for common tasks + like linting, testing, and creating releases, helping to ensure code + quality and streamline the development process. ## How to Use This Repository -This repository is intended to be used as a [GitHub Template](https://docs.github.com/en/repositories/creating-a-repository-on-github/creating-a-repository-from-a-template). Click the "Use this template" button at the top of the repository page to create your own new repository with the same structure and files. +This repository is intended to be used as a +[GitHub Template](https://docs.github.com/en/repositories/creating-a-repository-on-github/creating-a-repository-from-a-template). +Click the "Use this template" button at the top of the repository page to +create your own new repository with the same structure and files. diff --git a/docs/cicd.secrets-management.md b/docs/cicd.secrets-management.md index cc5b8ba..531fd3e 100644 --- a/docs/cicd.secrets-management.md +++ b/docs/cicd.secrets-management.md @@ -1,10 +1,17 @@ # 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. +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. +**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: @@ -14,20 +21,27 @@ Leaked secrets can lead to: ## Using GitHub Actions Secrets -GitHub provides a secure way to store and use secrets within your repository for use in GitHub Actions workflows. +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. +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. +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**. @@ -35,9 +49,11 @@ GitHub provides a secure way to store and use secrets within your repository for ### 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. +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: +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 @@ -53,6 +69,10 @@ Here's an example of a workflow step that uses a secret to publish a package to 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. +- 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. +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. diff --git a/docs/cicd.workflow-scheduling.md b/docs/cicd.workflow-scheduling.md index 2c8272d..f891436 100644 --- a/docs/cicd.workflow-scheduling.md +++ b/docs/cicd.workflow-scheduling.md @@ -1,10 +1,15 @@ # 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. +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. +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: @@ -12,7 +17,8 @@ on: - cron: "30 5 * * 1-5" ``` -This example triggers the workflow at 5:30 AM UTC every day from Monday to Friday. +This example triggers the workflow at 5:30 AM UTC every day from Monday to +Friday. ## Understanding Cron Syntax @@ -31,10 +37,14 @@ A cron expression is a string of five fields that represent a time schedule. ### 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. +- `*`: 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 @@ -48,7 +58,8 @@ A cron expression is a string of five fields that represent a time schedule. ## Example Workflow -Here is a complete example of a workflow that runs a script every day at midnight UTC. +Here is a complete example of a workflow that runs a script every day at +midnight UTC. ```yaml # .github/workflows/nightly-build.yml @@ -73,14 +84,25 @@ jobs: ## Best Practices -1. **Use UTC:** All scheduled times are in Coordinated Universal Time (UTC). Be sure to account for time zone differences. +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. +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. +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. +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. +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. +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/cicd.workflows.md b/docs/cicd.workflows.md index dbfbfb6..ce11fa1 100644 --- a/docs/cicd.workflows.md +++ b/docs/cicd.workflows.md @@ -1,15 +1,21 @@ # GitHub Workflows Documentation -This document explains the purpose and usage of the GitHub Actions workflows included in this repository. +This document explains the purpose and usage of the GitHub Actions workflows +included in this repository. ## [`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. +- **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`](../.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`](../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`](../.github/workflows/release-on-tag.yml) @@ -17,7 +23,11 @@ This document explains the purpose and usage of the GitHub Actions workflows inc - **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`](../.github/RELEASE_TITLE.txt) and [`.github/RELEASE_BODY.md`](../.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. + 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/community.building.md b/docs/community.building.md index 55a3f21..33326f8 100644 --- a/docs/community.building.md +++ b/docs/community.building.md @@ -1,42 +1,72 @@ # Community Building Guide -A thriving open-source project is built on a foundation of a healthy, welcoming, and effective community. Here are some best practices for fostering such an environment. +A thriving open-source project is built on a foundation of a healthy, +welcoming, and effective community. +Here are some best practices for fostering such an environment. ## 1. Establish a Code of Conduct -A [Code of Conduct](../CODE_OF_CONDUCT.md) is a document that outlines the expected standards of behavior for all community members. It's a clear statement that your project is a safe and inclusive space. +A [Code of Conduct](../CODE_OF_CONDUCT.md) is a document that outlines the +expected standards of behavior for all community members. +It's a clear statement that your project is a safe and inclusive space. -- **Adopt a Standard:** You don't have to write one from scratch. The [Contributor Covenant](https://www.contributor-covenant.org/) is a widely used and respected choice. This repository includes a template to get you started. -- **Enforce It:** A Code of Conduct is only effective if it's enforced. Be prepared to act on reports of violations to protect your community. +- **Adopt a Standard:** You don't have to write one from scratch. + The [Contributor Covenant](https://www.contributor-covenant.org/) is a + widely used and respected choice. + This repository includes a template to get you started. +- **Enforce It:** A Code of Conduct is only effective if it's enforced. + Be prepared to act on reports of violations to protect your community. ## 2. Be Welcoming and Responsive -First impressions matter. How you treat newcomers will determine whether they stick around. +First impressions matter. +How you treat newcomers will determine whether they stick around. -- **Welcome Contributions:** Use a `CONTRIBUTING.md` file to explain how people can contribute. Thank contributors for their work, even if you don't merge it. -- **Be Responsive:** Respond to issues and pull requests in a timely manner. If you're busy, a quick "Thanks for the report, I'll look into this next week" is better than silence. +- **Welcome Contributions:** Use a `CONTRIBUTING.md` file to explain how + people can contribute. + Thank contributors for their work, even if you don't merge it. +- **Be Responsive:** Respond to issues and pull requests in a timely manner. + If you're busy, a quick "Thanks for the report, I'll look into this next + week" is better than silence. ## 3. Provide Clear Communication Channels Designate specific places for different types of community interaction. -- **GitHub Issues:** Use issues for actionable tasks like bug reports and feature requests. This repository's [issue templates](./.github/ISSUE_TEMPLATE/) help structure this process. -- **GitHub Discussions:** Enable [GitHub Discussions](https://docs.github.com/en/discussions) for open-ended conversations, Q&A, and sharing ideas. This keeps your issue tracker focused. -- **Other Channels:** Consider a chat platform like Slack or Discord for more informal community interaction, but be mindful of the moderation overhead. +- **GitHub Issues:** Use issues for actionable tasks like bug reports and + feature requests. + This repository's [issue templates](./.github/ISSUE_TEMPLATE/) help + structure this process. +- **GitHub Discussions:** Enable + [GitHub Discussions](https://docs.github.com/en/discussions) for open-ended + conversations, Q&A, and sharing ideas. + This keeps your issue tracker focused. +- **Other Channels:** Consider a chat platform like Slack or Discord for more + informal community interaction, but be mindful of the moderation overhead. ## 4. Document Everything -Good documentation is a cornerstone of a healthy community. It empowers users to solve their own problems and lowers the barrier to contribution. +Good documentation is a cornerstone of a healthy community. +It empowers users to solve their own problems and lowers the barrier to +contribution. - **User Guides:** Write clear, concise guides for using your project. -- **Reference Material:** Provide detailed documentation for APIs, configuration options, and other technical aspects. -- **Contribution Guidelines:** Your `CONTRIBUTING.md` should clearly explain how to set up a development environment, run tests, and submit changes. +- **Reference Material:** Provide detailed documentation for APIs, + configuration options, and other technical aspects. +- **Contribution Guidelines:** Your `CONTRIBUTING.md` should clearly explain + how to set up a development environment, run tests, and submit changes. ## 5. Empower Your Community As your community grows, look for opportunities to empower trusted members. -- **Recognize Contributors:** Acknowledge valuable contributions publicly. This could be through release notes, social media shout-outs, or a contributors list in your README. -- **Delegate Responsibility:** Invite experienced community members to help triage issues, review pull requests, or moderate discussion channels. +- **Recognize Contributors:** Acknowledge valuable contributions publicly. + This could be through release notes, social media shout-outs, or a + contributors list in your README. +- **Delegate Responsibility:** Invite experienced community members to help + triage issues, review pull requests, or moderate discussion channels. -Building a community takes time and effort, but it's one of the most rewarding aspects of maintaining an open-source project. By being intentional about creating a positive and productive environment, you can build a project that lasts. +Building a community takes time and effort, but it's one of the most +rewarding aspects of maintaining an open-source project. +By being intentional about creating a positive and productive environment, you +can build a project that lasts. diff --git a/docs/community.discussions.md b/docs/community.discussions.md index 76327f8..a959d03 100644 --- a/docs/community.discussions.md +++ b/docs/community.discussions.md @@ -1,44 +1,72 @@ # Using GitHub Discussions -GitHub Discussions is a feature designed to be the community forum for your project, right alongside your code. -It provides a dedicated space for conversations, Q&A, and idea sharing, keeping your issue tracker clean and focused on actionable tasks. +GitHub Discussions is a feature designed to be the community forum for your +project, right alongside your code. +It provides a dedicated space for conversations, Q&A, and idea sharing, +keeping your issue tracker clean and focused on actionable tasks. ## Issues vs. Discussions: What's the Difference? -Understanding when to use Issues and when to use Discussions is key to keeping your project organized. +Understanding when to use Issues and when to use Discussions is key to +keeping your project organized. -- **GitHub Issues** are for tracking specific, actionable tasks. They have a clear "done" state. - - **Use for:** Bug reports, feature requests with a clear scope, specific to-do items. +- **GitHub Issues** are for tracking specific, actionable tasks. + They have a clear "done" state. + - **Use for:** Bug reports, feature requests with a clear scope, specific + to-do items. - **Example:** "The login button is broken on Safari." -- **GitHub Discussions** are for open-ended conversations. They don't have a "done" state and are about exploration and communication. - - **Use for:** Q&A, sharing ideas, general feedback, showing off what you've built. - - **Example:** "What do you think about adding a dark mode?" or "How do I connect the app to a different database?" +- **GitHub Discussions** are for open-ended conversations. + They don't have a "done" state and are about exploration and communication. + - **Use for:** Q&A, sharing ideas, general feedback, showing off what you've + built. + - **Example:** "What do you think about adding a dark mode?" or "How do I + connect the app to a different database?" -By directing non-actionable conversations to Discussions, you prevent your issue tracker from becoming cluttered with questions and long debates, allowing you to focus on the work that needs to be done. +By directing non-actionable conversations to Discussions, you prevent your +issue tracker from becoming cluttered with questions and long debates, +allowing you to focus on the work that needs to be done. ## How to Enable and Use Discussions -1. **Enable Discussions:** In your repository settings, under the "Features" section, check the box for "Discussions." +1. **Enable Discussions:** In your repository settings, under the "Features" + section, check the box for "Discussions." -2. **Configure Categories:** Set up categories to organize your community's conversations. Good starting categories include: +2. **Configure Categories:** Set up categories to organize your community's + conversations. + Good starting categories include: - **Announcements:** For maintainers to share project news. - - **Q&A:** For users to ask questions. This category has a feature to mark an answer as correct. + - **Q&A:** For users to ask questions. + This category has a feature to mark an answer as correct. - **Ideas:** For proposing and debating new features. - - **Show and Tell:** For community members to share what they've built with your project. + - **Show and Tell:** For community members to share what they've built + with your project. -See: [Managing categories for discussions](https://docs.github.com/en/discussions/managing-discussions-for-your-community/managing-categories-for-discussions) +See: +[Managing categories for discussions](https://docs.github.com/en/discussions/managing-discussions-for-your-community/managing-categories-for-discussions) ## Best Practices for Maintainers -1. **Seed the Conversation:** When you first enable Discussions, post a welcome message or an announcement to get things started. +1. **Seed the Conversation:** When you first enable Discussions, post a + welcome message or an announcement to get things started. -2. **Be Active:** Participate in discussions, answer questions, and encourage community members. Your engagement sets the tone. +2. **Be Active:** Participate in discussions, answer questions, and encourage + community members. + Your engagement sets the tone. -3. **Moderate as Needed:** As with any community forum, be prepared to moderate to ensure conversations remain respectful and productive, in line with your [Code of Conduct](./CODE_OF_CONDUCT.md). +3. **Moderate as Needed:** As with any community forum, be prepared to + moderate to ensure conversations remain respectful and productive, in line + with your [Code of Conduct](./CODE_OF_CONDUCT.md). -4. **Convert Issues to Discussions:** If a user opens an issue that is actually a question or a broad idea, you can convert it to a discussion. This moves the conversation to the right place while preserving the content. +4. **Convert Issues to Discussions:** If a user opens an issue that is + actually a question or a broad idea, you can convert it to a discussion. + This moves the conversation to the right place while preserving the + content. -5. **Convert Discussions to Issues:** Conversely, if a discussion evolves into a concrete, actionable task (like a well-defined feature request), you can create an issue directly from the discussion to track the work. +5. **Convert Discussions to Issues:** Conversely, if a discussion evolves + into a concrete, actionable task (like a well-defined feature request), + you can create an issue directly from the discussion to track the work. -By embracing GitHub Discussions, you can foster a vibrant community, gather valuable feedback, and maintain a clean, organized workflow for managing your project's development. +By embracing GitHub Discussions, you can foster a vibrant community, gather +valuable feedback, and maintain a clean, organized workflow for managing your +project's development. diff --git a/docs/community.issue-management.md b/docs/community.issue-management.md index 2912e82..9d64642 100644 --- a/docs/community.issue-management.md +++ b/docs/community.issue-management.md @@ -1,18 +1,30 @@ # Issue Management Guide -Effective issue management is key to keeping your project organized and your community engaged. This guide covers best practices for using GitHub Issues, labels, and templates to triage bug reports and feature requests. +Effective issue management is key to keeping your project organized and your +community engaged. +This guide covers best practices for using GitHub Issues, labels, and +templates to triage bug reports and feature requests. ## 1. Use Issue Templates -The first step to effective issue management is to get clear, structured information from contributors. GitHub's issue templates are perfect for this. +The first step to effective issue management is to get clear, structured +information from contributors. +GitHub's issue templates are perfect for this. -- **What they are:** Pre-populated templates for bug reports and feature requests that prompt the user for specific information. -- **Why they're useful:** They ensure you get the information you need to act on an issue, such as steps to reproduce a bug or the use case for a new feature. -- **How to use them:** This repository includes templates in the [`.github/ISSUE_TEMPLATE/`](../.github/ISSUE_TEMPLATE/) directory. You can customize them to fit your project's needs. +- **What they are:** Pre-populated templates for bug reports and feature + requests that prompt the user for specific information. +- **Why they're useful:** They ensure you get the information you need to act + on an issue, such as steps to reproduce a bug or the use case for a new + feature. +- **How to use them:** This repository includes templates in the + [`.github/ISSUE_TEMPLATE/`](../.github/ISSUE_TEMPLATE/) directory. + You can customize them to fit your project's needs. ## 2. Leverage Labels -Labels are a powerful tool for categorizing and prioritizing issues. A good set of labels makes it easy to see the state of your project at a glance. +Labels are a powerful tool for categorizing and prioritizing issues. +A good set of labels makes it easy to see the state of your project at a +glance. ### Recommended Label Categories @@ -29,35 +41,55 @@ Labels are a powerful tool for categorizing and prioritizing issues. A good set - `blocked`: An issue that cannot be worked on due to external factors. - **Priority:** - - `critical`: Must be addressed immediately (e.g., a security vulnerability). + - `critical`: Must be addressed immediately (e.g., a security + vulnerability). - `high`: Important and should be prioritized. - `medium`: A standard issue. - `low`: A non-urgent issue or nice-to-have feature. - **Contribution Welcome:** - - `good-first-issue`: A relatively simple issue that's a great entry point for new contributors. + - `good-first-issue`: A relatively simple issue that's a great entry point + for new contributors. - `help-wanted`: An issue that you'd like the community to help with. ## 3. The Triage Workflow -Triage is the process of reviewing new issues and preparing them for work. A typical workflow looks like this: +Triage is the process of reviewing new issues and preparing them for work. +A typical workflow looks like this: -1. **Review New Issues:** Regularly check for issues that don't have any labels or assignees. +1. **Review New Issues:** Regularly check for issues that don't have any + labels or assignees. -2. **Ensure Clarity:** If an issue is unclear, ask the author for more information. If they don't respond after a reasonable amount of time, it's okay to close the issue. +2. **Ensure Clarity:** If an issue is unclear, ask the author for more + information. + If they don't respond after a reasonable amount of time, it's okay to + close the issue. -3. **Reproduce Bugs:** For bug reports, try to reproduce the issue based on the information provided. If you can reproduce it, add a `confirmed` label. If not, ask for more details. +3. **Reproduce Bugs:** For bug reports, try to reproduce the issue based on + the information provided. + If you can reproduce it, add a `confirmed` label. + If not, ask for more details. -4. **Apply Labels:** Add the appropriate `type`, `status`, and `priority` labels to the issue. +4. **Apply Labels:** Add the appropriate `type`, `status`, and `priority` + labels to the issue. 5. **Engage with the Community:** - - For valid feature requests, discuss the proposal with the community to gauge interest and gather ideas. - - For issues you won't address, explain why and close the issue respectfully. - - For issues that are good for new contributors, add a `good-first-issue` label and perhaps a comment with pointers on how to get started. + - For valid feature requests, discuss the proposal with the community to + gauge interest and gather ideas. + - For issues you won't address, explain why and close the issue + respectfully. + - For issues that are good for new contributors, add a `good-first-issue` + label and perhaps a comment with pointers on how to get started. ## 4. Use Milestones and Projects -- **Milestones:** Group issues together for a specific release (e.g., `v1.1.0`). This helps you track progress towards your next version. -- **GitHub Projects:** For more complex work, use a project board to visualize and manage the workflow of issues and pull requests, similar to a Kanban board. +- **Milestones:** Group issues together for a specific release (e.g., + `v1.1.0`). + This helps you track progress towards your next version. +- **GitHub Projects:** For more complex work, use a project board to visualize + and manage the workflow of issues and pull requests, similar to a Kanban + board. -By implementing these practices, you can create a clear, organized, and efficient issue management process that will benefit both you and your contributors. +By implementing these practices, you can create a clear, organized, and +efficient issue management process that will benefit both you and your +contributors. diff --git a/docs/community.wiki.md b/docs/community.wiki.md index e7d9809..efc7b88 100644 --- a/docs/community.wiki.md +++ b/docs/community.wiki.md @@ -1,37 +1,66 @@ # Using the GitHub Wiki -The GitHub Wiki is a powerful tool for hosting detailed, long-form documentation for your project. Unlike your repository's `README.md` file, which is meant to be a quick introduction, the wiki provides a dedicated space for comprehensive guides, tutorials, and reference material. +The GitHub Wiki is a powerful tool for hosting detailed, long-form documentation +for your project. +Unlike your repository's `README.md` file, which is meant to be a quick +introduction, the wiki provides a dedicated space for comprehensive guides, +tutorials, and reference material. ## `README.md` vs. Wiki: What's the Difference? -Understanding when to use your `README.md` and when to use the wiki is key to keeping your project's documentation organized and accessible. +Understanding when to use your `README.md` and when to use the wiki is key to +keeping your project's documentation organized and accessible. -- **`README.md`** is the front door to your project. It should be concise and provide a high-level overview, installation instructions, and a quick start guide. It's the first thing most visitors will see. +- **`README.md`** is the front door to your project. + It should be concise and provide a high-level overview, installation + instructions, and a quick start guide. + It's the first thing most visitors will see. -- **The Wiki** is the library for your project. It's the place for "deep dive" content that doesn't fit in the README. - - **Use for:** In-depth tutorials, API references, design documents, project history, and FAQs. - - **Example:** A detailed guide on "Advanced Configuration Options" or a "Contributor's Guide to the Codebase." +- **The Wiki** is the library for your project. + It's the place for "deep dive" content that doesn't fit in the README. + - **Use for:** In-depth tutorials, API references, design documents, project + history, and FAQs. + - **Example:** A detailed guide on "Advanced Configuration Options" or a + "Contributor's Guide to the Codebase." -By moving detailed documentation to the wiki, you keep your `README.md` clean and focused, while providing a structured and searchable home for your project's knowledge base. +By moving detailed documentation to the wiki, you keep your `README.md` clean +and focused, while providing a structured and searchable home for your +project's knowledge base. ## How to Use the Wiki -1. **Enable the Wiki:** In your repository settings, under the "Features" section, check the box for "Wiki." +1. **Enable the Wiki:** In your repository settings, under the "Features" + section, check the box for "Wiki." -2. **Create a Home Page:** Every wiki starts with a `Home.md` page. This page should serve as a table of contents, with links to all the other pages in your wiki. +2. **Create a Home Page:** Every wiki starts with a `Home.md` page. + This page should serve as a table of contents, with links to all the other + pages in your wiki. -3. **Add and Edit Pages:** You can add new pages and edit existing ones directly in the GitHub web interface. The wiki uses Markdown, just like the rest of GitHub. +3. **Add and Edit Pages:** You can add new pages and edit existing ones + directly in the GitHub web interface. + The wiki uses Markdown, just like the rest of GitHub. -4. **Link Pages Together:** Create links between your wiki pages to build a cohesive and navigable documentation site. You can link to another wiki page using the syntax `[[Page Name]]`. +4. **Link Pages Together:** Create links between your wiki pages to build a + cohesive and navigable documentation site. + You can link to another wiki page using the syntax `[[Page Name]]`. ## Best Practices for Maintainers -1. **Keep it Organized:** Use the `Home.md` page as a table of contents. Group related pages together with clear and consistent naming. +1. **Keep it Organized:** Use the `Home.md` page as a table of contents. + Group related pages together with clear and consistent naming. -2. **Encourage Contributions:** By default, anyone with push access to your repository can edit the wiki. Encourage your community to contribute to the documentation. +2. **Encourage Contributions:** By default, anyone with push access to your + repository can edit the wiki. + Encourage your community to contribute to the documentation. -3. **Review and Curate:** Periodically review the content of your wiki to ensure it is up-to-date and accurate. Remove outdated information and refactor pages as your project evolves. +3. **Review and Curate:** Periodically review the content of your wiki to + ensure it is up-to-date and accurate. + Remove outdated information and refactor pages as your project evolves. -4. **Link to the Wiki from your `README.md`:** Add a link to your wiki from your project's `README.md` file so that visitors can easily find your detailed documentation. +4. **Link to the Wiki from your `README.md`:** Add a link to your wiki from + your project's `README.md` file so that visitors can easily find your + detailed documentation. -By leveraging the GitHub Wiki, you can build a comprehensive and collaborative documentation site that will help your users and contributors get the most out of your project. +By leveraging the GitHub Wiki, you can build a comprehensive and collaborative +documentation site that will help your users and contributors get the most out +of your project. diff --git a/docs/deployment.render.md b/docs/deployment.render.md index 89b95d8..6779979 100644 --- a/docs/deployment.render.md +++ b/docs/deployment.render.md @@ -1,15 +1,20 @@ # Deploying to Render.com -This repository is configured for continuous deployment to [Render.com](https://render.com/) on their free tier. +This repository is configured for continuous deployment to [Render.com](https://render.com/) +on their free tier. ## How It Works -The deployment is defined using infrastructure-as-code in the `render.yaml` file at the root of the repository. This file tells Render to: +The deployment is defined using infrastructure-as-code in the `render.yaml` +file at the root of the repository. +This file tells Render to: 1. **Create a Web Service:** Define a service of type `web`. -2. **Use Docker:** Use the `docker` environment to build and deploy the service. +2. **Use Docker:** Use the `docker` environment to build and deploy the + service. 3. **Use the Free Plan:** Deploy the service on the free instance type. -4. **Configure Health Checks:** Use the `/` path to perform health checks, ensuring the service is running correctly. +4. **Configure Health Checks:** Use the `/` path to perform health checks, + ensuring the service is running correctly. ## Getting Started @@ -20,4 +25,5 @@ To deploy this repository to your own Render account: 3. Render will automatically detect and use the `render.yaml` file. 4. Approve the plan, and Render will build and deploy the service. -Any subsequent pushes to your `main` branch will automatically trigger a new deployment on Render. +Any subsequent pushes to your `main` branch will automatically trigger a new +deployment on Render. diff --git a/docs/development.codespaces.md b/docs/development.codespaces.md index 0be613f..11c196a 100644 --- a/docs/development.codespaces.md +++ b/docs/development.codespaces.md @@ -1,13 +1,21 @@ # GitHub Codespaces -This repository is configured to use [GitHub Codespaces](https://github.com/features/codespaces) to provide a complete, cloud-based development environment. +This repository is configured to use +[GitHub Codespaces](https://github.com/features/codespaces) to provide a +complete, cloud-based development environment. ## How It Works -The configuration is defined in the [`.devcontainer/devcontainer.json`](../.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`](../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. +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 @@ -17,13 +25,16 @@ To get started with Codespaces: 2. Select the **"Codespaces"** tab. 3. Click **"Create codespace on main"**. -GitHub will prepare your cloud environment, and you will be taken to a web-based version of VS Code, fully configured and ready to go. The terminal within VS Code will be inside the running development container. +GitHub will prepare your cloud environment, and you will be taken to a +web-based version of VS Code, fully configured and ready to go. +The terminal within VS Code will be inside the running development container. ## How to Serve the "pong" Page on Port 80 in a New GitHub Codespace 1. **Open a Codespace:** - Go to your repository on GitHub. - - Click the **Code** button, select the **Codespaces** tab, and create a new Codespace. + - Click the **Code** button, select the **Codespaces** tab, and create a + new Codespace. 2. **Start NGINX in the Dev Container:** - Open the integrated terminal in VS Code. @@ -36,10 +47,12 @@ GitHub will prepare your cloud environment, and you will be taken to a web-based - Open the **PORTS** tab (bottom panel, tiny icon). - Click the **Forward a Port** button (`+` icon). - Enter `80` as the port number and confirm. - - The url to your codespace instance will now appear in the 'Forwarded Ports' column + - The url to your codespace instance will now appear in the 'Forwarded + Ports' column 4. **Open the "pong" Page:** - - Copy the forwarded URL shown in the PORTS tab (it will look like `https://-80.app.github.dev/`). + - Copy the forwarded URL shown in the PORTS tab (it will look like + `https://-80.app.github.dev/`). - Open it in your browser: ```bash "$BROWSER" https://-80.app.github.dev/ diff --git a/docs/development.docker.md b/docs/development.docker.md index 3d7cd9d..71f83c8 100644 --- a/docs/development.docker.md +++ b/docs/development.docker.md @@ -1,32 +1,53 @@ # Docker-based Development Environment -This repository includes a Docker-based development environment to ensure a consistent and reproducible setup for all contributors. +This repository includes a Docker-based development environment to ensure a +consistent and reproducible setup for all contributors. ## Components The environment is defined by several files: -- **[`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. +- **[`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 -To use the development environment, you must have [Docker](https://www.docker.com/get-started) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your system. +To use the development environment, you must have +[Docker](https://www.docker.com/get-started) and +[Docker Compose](https://docs.docker.com/compose/install/) installed on your +system. 1. **Build and Run the Container:** - Open a terminal in the root of the repository and run the following command: + Open a terminal in the root of the repository and run the following + command: ```bash docker-compose up -d ``` - This will build the Docker image (if it's the first time) and start the container in the background. + This will build the Docker image (if it's the first time) and start the + container in the background. 2. **Verify It's Running:** - Open your web browser and navigate to `http://localhost:8080`. You should see the word `pong`. + Open your web browser and navigate to `http://localhost:8080`. + You should see the word `pong`. 3. **Access the Environment:** To open a shell inside the running container, use the following command: @@ -35,7 +56,8 @@ To use the development environment, you must have [Docker](https://www.docker.co docker-compose exec dev /bin/bash ``` - You will now be inside the Ubuntu environment, where you can install any language-specific tools (like Python, Node.js, etc.) and run your code. + You will now be inside the Ubuntu environment, where you can install any + language-specific tools (like Python, Node.js, etc.) and run your code. 4. **Stopping the Environment:** To stop the container, run: @@ -45,7 +67,9 @@ 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`](../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/development.package-json.md b/docs/development.package-json.md index 5455b2f..a5990c9 100644 --- a/docs/development.package-json.md +++ b/docs/development.package-json.md @@ -1,19 +1,43 @@ # `package.json` and `package-lock.json` -You may notice `package.json` and `package-lock.json` files in the root of this repository. These files are part of the Node.js ecosystem and are used to manage project dependencies and scripts. +You may notice `package.json` and `package-lock.json` files in the root of +this repository. +These files are part of the Node.js ecosystem and are used to manage project +dependencies and scripts. ## What is their Purpose in `base`? -The `attogram/base` template is designed to be language-agnostic. However, it does use a few Node.js-based tools for development purposes to ensure code quality and consistency. - -- **`package.json`**: This file lists the development dependencies required to work on this repository. Primarily, this includes `prettier`, a code formatter that automatically ensures all configuration files and documentation adhere to a consistent style. It may also contain simple scripts that can be run with `npm run `. - -- **`package-lock.json`**: This is an auto-generated file that records the exact version of every dependency used. This guarantees that every developer (and every AI agent) uses the exact same version of the tools, preventing inconsistencies and "it works on my machine" problems. **You should not edit this file manually.** +The `attogram/base` template is designed to be language-agnostic. +However, it does use a few Node.js-based tools for development purposes to +ensure code quality and consistency. + +- **`package.json`**: This file lists the development dependencies required to + work on this repository. + Primarily, this includes `prettier`, a code formatter that automatically + ensures all configuration files and documentation adhere to a consistent + style. + It may also contain simple scripts that can be run with + `npm run `. + +- **`package-lock.json`**: This is an auto-generated file that records the + exact version of every dependency used. + This guarantees that every developer (and every AI agent) uses the exact + same version of the tools, preventing inconsistencies and "it works on my + machine" problems. + **You should not edit this file manually.** ## Do I Need Node.js? -Strictly speaking, you only need Node.js and `npm` installed if you intend to run the development tools yourself, such as running `npx prettier --write .` to format files. +Strictly speaking, you only need Node.js and `npm` installed if you intend to +run the development tools yourself, such as running +`npx prettier --write .` to format files. -The AI agents that work on this repository are expected to have these tools available and will use them to keep the codebase consistent. If you ask an AI agent to perform work, it will use these files to ensure its changes match the project's standards. +The AI agents that work on this repository are expected to have these tools +available and will use them to keep the codebase consistent. +If you ask an AI agent to perform work, it will use these files to ensure its +changes match the project's standards. -If you are not a developer and are only using this repository to manage content, you can generally ignore these files. They are part of the "scaffolding" that keeps the project clean and maintainable. +If you are not a developer and are only using this repository to manage +content, you can generally ignore these files. +They are part of the "scaffolding" that keeps the project clean and +maintainable. diff --git a/docs/development.prettier-workflow.md b/docs/development.prettier-workflow.md index cf85aec..b0954d6 100644 --- a/docs/development.prettier-workflow.md +++ b/docs/development.prettier-workflow.md @@ -1,6 +1,9 @@ # Prettier Workflow -This repository includes a GitHub Actions workflow that automatically formats all files in the repository using [Prettier](https://prettier.io/), a widely-used code formatter. This ensures a consistent and readable code style across the entire project. +This repository includes a GitHub Actions workflow that automatically formats +all files in the repository using [Prettier](https://prettier.io/), a +widely-used code formatter. +This ensures a consistent and readable code style across the entire project. ## Workflow Details @@ -12,11 +15,20 @@ This repository includes a GitHub Actions workflow that automatically formats al 1. Check out the code from the relevant branch or pull request. 2. Install the necessary dependencies (`npm install`). 3. Run `npx prettier --write .` to format all files. - 4. If any files were changed by Prettier, the workflow will automatically commit the changes back to the same branch (for pushes) or the pull request's head branch with the commit message `style: Format code with Prettier`. + 4. If any files were changed by Prettier, the workflow will automatically + commit the changes back to the same branch (for pushes) or the pull + request's head branch with the commit message + `style: Format code with Prettier`. ## How it Works The workflow runs automatically, so there are no manual steps required. -- **On the `main` branch:** When code is pushed to `main`, the workflow will run and commit any formatting changes directly to `main`. -- **On Pull Requests:** When you open a pull request, the workflow will run on the code in your branch. If it finds any formatting issues, it will push a new commit to your branch with the fixes. This helps ensure that all code is properly formatted before it gets merged into `main`. +- **On the `main` branch:** When code is pushed to `main`, the workflow will + run and commit any formatting changes directly to `main`. +- **On Pull Requests:** When you open a pull request, the workflow will run on + the code in your branch. + If it finds any formatting issues, it will push a new commit to your branch + with the fixes. + This helps ensure that all code is properly formatted before it gets merged + into `main`. diff --git a/docs/development.prettier.md b/docs/development.prettier.md index 7012958..4a21608 100644 --- a/docs/development.prettier.md +++ b/docs/development.prettier.md @@ -1,12 +1,17 @@ # Prettier -Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary. +Prettier is an opinionated code formatter. +It enforces a consistent style by parsing your code and re-printing it with +its own rules that take the maximum line length into account, wrapping code +when necessary. -This document provides instructions on how to install and run Prettier in your project. +This document provides instructions on how to install and run Prettier in your +project. ## Installation -The recommended approach is to install Prettier locally as a development dependency. +The recommended approach is to install Prettier locally as a development +dependency. ### npm @@ -32,9 +37,13 @@ pnpm add --save-dev --save-exact prettier bun add --dev --exact prettier ``` -This repository includes a default configuration file, [`.prettierrc`](../.prettierrc), so you don't need to create one from scratch. It lets editors and other tools know that you are using Prettier. +This repository includes a default configuration file, +[`.prettierrc`](../.prettierrc), so you don't need to create one from +scratch. +It lets editors and other tools know that you are using Prettier. -It is also useful to create a `.prettierignore` file to specify which files should not be formatted by Prettier. +It is also useful to create a `.prettierignore` file to specify which files +should not be formatted by Prettier. ```bash echo "# Ignore artifacts:\nbuild\ncoverage" > .prettierignore @@ -42,7 +51,8 @@ echo "# Ignore artifacts:\nbuild\ncoverage" > .prettierignore ## Usage -Once Prettier is installed, you can run it from the command line to format your files. +Once Prettier is installed, you can run it from the command line to format +your files. ### Format all files @@ -69,10 +79,14 @@ npx prettier "app/**/*.test.js" --write ### Check for formatting issues -In a Continuous Integration (CI) environment, you can use the `--check` flag to verify that all files are formatted correctly without actually modifying them. This is useful for enforcing a consistent code style. +In a Continuous Integration (CI) environment, you can use the `--check` flag +to verify that all files are formatted correctly without actually modifying +them. +This is useful for enforcing a consistent code style. ```bash npx prettier . --check ``` -For more information, please refer to the official [Prettier documentation](https://prettier.io/docs/en/install.html). +For more information, please refer to the official +[Prettier documentation](https://prettier.io/docs/en/install.html). diff --git a/docs/documentation.best-practices.md b/docs/documentation.best-practices.md index 12e39b1..c3397b5 100644 --- a/docs/documentation.best-practices.md +++ b/docs/documentation.best-practices.md @@ -1,44 +1,78 @@ # Documentation Best Practices -Good documentation is one of the most important aspects of a successful software project. It empowers users, reduces the support burden on maintainers, and encourages contributions. This guide covers the art of writing clear and effective documentation. +Good documentation is one of the most important aspects of a successful +software project. +It empowers users, reduces the support burden on maintainers, and encourages +contributions. +This guide covers the art of writing clear and effective documentation. ## The Two Types of Documentation -It's helpful to think of documentation in two main categories: user guides and reference material. A good project has both. +It's helpful to think of documentation in two main categories: user guides +and reference material. +A good project has both. ### 1. User Guides (Tutorials) -- **Purpose:** To teach a user how to accomplish a specific task. They are action-oriented. +- **Purpose:** To teach a user how to accomplish a specific task. + They are action-oriented. - **Audience:** New users or users trying to solve a particular problem. -- **Format:** A step-by-step walkthrough. They tell a story. -- **Example:** A guide on "How to deploy this application to a server" or "How to build your first plugin." +- **Format:** A step-by-step walkthrough. + They tell a story. +- **Example:** A guide on "How to deploy this application to a server" or "How + to build your first plugin." -User guides are like a teacher showing a student how to do something. They should be easy to follow and focused on a practical outcome. +User guides are like a teacher showing a student how to do something. +They should be easy to follow and focused on a practical outcome. ### 2. Reference Material (The Dictionary) -- **Purpose:** To provide a comprehensive, factual description of the system. It is information-oriented. -- **Audience:** Users who already have some familiarity with the project and need specific, detailed information. +- **Purpose:** To provide a comprehensive, factual description of the system. + It is information-oriented. +- **Audience:** Users who already have some familiarity with the project and + need specific, detailed information. - **Format:** Organized by topic, like a dictionary or an encyclopedia. -- **Example:** A complete list of all available API endpoints and their parameters, or a detailed description of every configuration option in a file. +- **Example:** A complete list of all available API endpoints and their + parameters, or a detailed description of every configuration option in a + file. -Reference material is like a technical manual. It should be accurate, exhaustive, and well-organized so that users can quickly find the exact information they need. +Reference material is like a technical manual. +It should be accurate, exhaustive, and well-organized so that users can +quickly find the exact information they need. ## The Importance of Good Examples -Code examples are the heart of good documentation. They bridge the gap between theory and practice. +Code examples are the heart of good documentation. +They bridge the gap between theory and practice. -- **Make them practical:** Examples should demonstrate a real-world use case, not just the syntax of a function. -- **Make them copy-pasteable:** Ensure that examples can be copied and run directly without modification. This means including any necessary setup or import statements. -- **Keep them up-to-date:** There's nothing more frustrating than documentation with outdated examples. As your code evolves, make sure your examples do too. +- **Make them practical:** Examples should demonstrate a real-world use case, + not just the syntax of a function. +- **Make them copy-pasteable:** Ensure that examples can be copied and run + directly without modification. + This means including any necessary setup or import statements. +- **Keep them up-to-date:** There's nothing more frustrating than + documentation with outdated examples. + As your code evolves, make sure your examples do too. ## Tips for Writing Good Docs -1. **Know Your Audience:** Write for your users, not for yourself. Avoid jargon where possible, or explain it if it's necessary. -2. **Be Concise:** Get to the point. Users are often looking for a quick solution to a problem. -3. **Use a Clear Structure:** Use headings, lists, and code blocks to make your documentation easy to scan. -4. **Add Visuals:** Screenshots, diagrams, and GIFs can often explain a concept more effectively than text alone. -5. **Document the "Why":** Don't just explain _what_ something does; explain _why_ a user might want to use it. Provide context. -6. **Treat Docs like Code:** Documentation should be part of your development process. When you add a new feature or make a change, update the docs at the same time. Include documentation in your code review process. +1. **Know Your Audience:** Write for your users, not for yourself. + Avoid jargon where possible, or explain it if it's necessary. +2. **Be Concise:** Get to the point. + Users are often looking for a quick solution to a problem. +3. **Use a Clear Structure:** Use headings, lists, and code blocks to make + your documentation easy to scan. +4. **Add Visuals:** Screenshots, diagrams, and GIFs can often explain a + concept more effectively than text alone. +5. **Document the "Why":** Don't just explain _what_ something does; explain + _why_ a user might want to use it. + Provide context. +6. **Treat Docs like Code:** Documentation should be part of your + development process. + When you add a new feature or make a change, update the docs at the same + time. + Include documentation in your code review process. -Writing documentation is a continuous process of refinement. By investing in clear, comprehensive, and user-focused documentation, you are investing in the long-term success of your project. +Writing documentation is a continuous process of refinement. +By investing in clear, comprehensive, and user-focused documentation, you are +investing in the long-term success of your project. diff --git a/docs/guides.software-project.md b/docs/guides.software-project.md index 92bf59b..749928b 100644 --- a/docs/guides.software-project.md +++ b/docs/guides.software-project.md @@ -1,28 +1,49 @@ # Use Case: A Starting Point for Your Software Project -This repository is designed to be a robust foundation for a wide variety of software projects. It provides a standardized, best-practice setup that lets you focus on writing code, not on boilerplate and configuration. +This repository is designed to be a robust foundation for a wide variety of +software projects. +It provides a standardized, best-practice setup that lets you focus on +writing code, not on boilerplate and configuration. -This guide will walk you through how to adapt this template for different kinds of software projects, with examples for common languages and platforms. +This guide will walk you through how to adapt this template for different +kinds of software projects, with examples for common languages and platforms. ## Core Philosophy: A "Batteries-Included" Template -The `base` repository is built on the idea that a good starting point can save hours or even days of setup time. It provides: +The `base` repository is built on the idea that a good starting point can +save hours or even days of setup time. +It provides: -- **A Consistent Development Environment:** Using Docker and GitHub Codespaces, everyone on your team has the same setup, eliminating "it works on my machine" problems. -- **Automated Workflows:** GitHub Actions are pre-configured for common tasks like linting, testing, and continuous integration. -- **Standardized Tooling:** Pre-configured tools like Prettier for code formatting ensure consistency across the codebase. -- **Clear Documentation:** A `docs` directory and a GitHub Pages site are ready for you to document your project. +- **A Consistent Development Environment:** Using Docker and GitHub Codespaces, + everyone on your team has the same setup, eliminating "it works on my + machine" problems. +- **Automated Workflows:** GitHub Actions are pre-configured for common tasks + like linting, testing, and continuous integration. +- **Standardized Tooling:** Pre-configured tools like Prettier for code + formatting ensure consistency across the codebase. +- **Clear Documentation:** A `docs` directory and a GitHub Pages site are + ready for you to document your project. ## Part 1: Structuring Your Project -While this template provides a solid base, you'll need to add your own application code. Here are some recommended structures for different project types. +While this template provides a solid base, you'll need to add your own +application code. +Here are some recommended structures for different project types. ### General Recommendations -- **Source Code:** Keep your main application code in a dedicated directory. Common choices are `src/`, `app/`, or a directory named after your project. -- **Tests:** Keep your tests separate from your application code, but in a way that mirrors the source structure. A top-level `tests/` or `spec/` directory is a common pattern. -- **Scripts:** Place helper scripts, build scripts, or deployment scripts in a `scripts/` directory. -- **Configuration:** While this template provides global configuration (`.editorconfig`, `.gitignore`), your application will have its own configuration. Store these in a `config/` directory or at the root of the project, depending on the framework. +- **Source Code:** Keep your main application code in a dedicated directory. + Common choices are `src/`, `app/`, or a directory named after your project. +- **Tests:** Keep your tests separate from your application code, but in a way + that mirrors the source structure. + A top-level `tests/` or `spec/` directory is a common pattern. +- **Scripts:** Place helper scripts, build scripts, or deployment scripts in a + `scripts/` directory. +- **Configuration:** While this template provides global configuration + (`.editorconfig`, `.gitignore`), your application will have its own + configuration. + Store these in a `config/` directory or at the root of the project, + depending on the framework. --- @@ -32,7 +53,8 @@ Here's how you can adapt this template for some popular platforms. ### Example: A Node.js Application -Node.js is a popular choice for building web servers, APIs, and command-line tools. +Node.js is a popular choice for building web servers, APIs, and command-line +tools. **1. Project Structure:** @@ -66,7 +88,8 @@ npm install --save-dev jest supertest **3. Configuring `package.json`:** -Your `package.json` is the heart of your Node.js project. You'll add scripts for common tasks. +Your `package.json` is the heart of your Node.js project. +You'll add scripts for common tasks. ```json "scripts": { @@ -79,7 +102,8 @@ Your `package.json` is the heart of your Node.js project. You'll add scripts for **4. Docker Configuration (`docker-compose.yml`):** -To run your Node.js app in the development environment, you can add a service to the `docker-compose.yml` file. +To run your Node.js app in the development environment, you can add a service +to the `docker-compose.yml` file. ```yaml services: @@ -98,7 +122,8 @@ Laravel is a powerful PHP framework for building web applications. **1. Project Structure:** -Laravel has its own prescribed directory structure, which you can create within this template. +Laravel has its own prescribed directory structure, which you can create +within this template. ``` . @@ -130,7 +155,8 @@ php artisan key:generate **3. Docker Configuration (`docker-compose.yml`):** -A Laravel setup often requires multiple services (PHP, a web server like Nginx, a database like MySQL). +A Laravel setup often requires multiple services (PHP, a web server like +Nginx, a database like MySQL). ```yaml services: @@ -201,7 +227,8 @@ go build -o myapp ./cmd/myapp **4. Docker Configuration (`Dockerfile`):** -Go applications are often deployed as small, static binaries in a minimal Docker image. +Go applications are often deployed as small, static binaries in a minimal +Docker image. ```dockerfile # build stage @@ -247,11 +274,13 @@ chmod +x scripts/*.sh **3. Testing Bash Scripts:** -You can use a testing framework like `shellcheck` for static analysis and `bats-core` for unit testing. +You can use a testing framework like `shellcheck` for static analysis and +`bats-core` for unit testing. **`package.json` for Tooling:** -Even for a Bash project, you can use `package.json` to manage your testing tools. +Even for a Bash project, you can use `package.json` to manage your testing +tools. ```json "scripts": { @@ -267,7 +296,8 @@ npm install --save-dev shellcheck bats-core ### Example: A Plain JavaScript/Frontend Project -For a project without a heavy framework, you can structure it for serving static HTML, CSS, and JS files. +For a project without a heavy framework, you can structure it for serving +static HTML, CSS, and JS files. **1. Project Structure:** @@ -286,7 +316,8 @@ For a project without a heavy framework, you can structure it for serving static **2. Development Tooling (`package.json`):** -Use `npm` scripts for development tasks like running a local server and building your assets. +Use `npm` scripts for development tasks like running a local server and +building your assets. ```json "scripts": { @@ -302,24 +333,32 @@ npm install --save-dev live-server **3. GitHub Pages Deployment:** -This setup is perfect for deploying to GitHub Pages. You can configure a GitHub Action to run your `npm run build` command and deploy the contents of the `dist/` folder. +This setup is perfect for deploying to GitHub Pages. +You can configure a GitHub Action to run your `npm run build` command and +deploy the contents of the `dist/` folder. -See the **[Use Case: A Publishing Platform](./use-case-publishing.md)** guide for more details on this approach. +See the **[Use Case: A Publishing Platform](./use-case-publishing.md)** guide +for more details on this approach. --- ## Part 3: Adapting the CI/CD Workflows -The included GitHub Actions in `.github/workflows/` provide a starting point. You'll likely want to customize them for your project. +The included GitHub Actions in `.github/workflows/` provide a starting point. +You'll likely want to customize them for your project. ### Customizing the `ci.yml` Workflow The main `ci.yml` workflow is a good place to add steps for: -- **Installing Dependencies:** Add a step to run `npm install`, `composer install`, or `go get`. -- **Running Tests:** Add a step to execute your test suite (`npm test`, `php artisan test`, `go test`). -- **Building Your Application:** If your project needs a build step, add it here. -- **Linting:** The workflow already includes `prettier`. You can add other linters like `eslint` or `shellcheck`. +- **Installing Dependencies:** Add a step to run `npm install`, + `composer install`, or `go get`. +- **Running Tests:** Add a step to execute your test suite (`npm test`, + `php artisan test`, `go test`). +- **Building Your Application:** If your project needs a build step, add it + here. +- **Linting:** The workflow already includes `prettier`. + You can add other linters like `eslint` or `shellcheck`. **Example: `ci.yml` step for a Node.js project** @@ -333,4 +372,7 @@ The main `ci.yml` workflow is a good place to add steps for: ## Conclusion -This `base` repository is a powerful and flexible starting point. By understanding its core components and how to adapt them, you can bootstrap your next software project quickly and efficiently, ensuring you start with a solid, maintainable, and well-structured foundation. +This `base` repository is a powerful and flexible starting point. +By understanding its core components and how to adapt them, you can bootstrap +your next software project quickly and efficiently, ensuring you start with a +solid, maintainable, and well-structured foundation. diff --git a/docs/project.badges.md b/docs/project.badges.md index 5d9e205..02d0b4e 100644 --- a/docs/project.badges.md +++ b/docs/project.badges.md @@ -1,28 +1,52 @@ # Badges -Badges are a common way to display the status of your project in your `README.md` file. They can provide information about your build status, code coverage, version, license, and more. They serve as a quick visual indicator of the health and status of your project. +Badges are a common way to display the status of your project in your +`README.md` file. +They can provide information about your build status, code coverage, version, +license, and more. +They serve as a quick visual indicator of the health and status of your +project. ## Badge Sources -While [Shields.io](https://shields.io/) is very popular because it offers a huge variety of badges with a consistent style, many services provide their own free badges directly. Here are a few examples of common sources: +While [Shields.io](https://shields.io/) is very popular because it offers a +huge variety of badges with a consistent style, many services provide their +own free badges directly. +Here are a few examples of common sources: -- **GitHub Actions:** As seen in the examples below, GitHub provides its own status badges for workflows. You can get the markdown for this directly from the "Actions" tab in your repository. +- **GitHub Actions:** As seen in the examples below, GitHub provides its own + status badges for workflows. + You can get the markdown for this directly from the "Actions" tab in your + repository. -- **CI/CD Services:** Services like [Travis CI](https://travis-ci.org/), [CircleCI](https://circleci.com/), and others provide status badges that you can embed in your README. +- **CI/CD Services:** Services like [Travis CI](https://travis-ci.org/), + [CircleCI](https://circleci.com/), and others provide status badges that + you can embed in your README. -- **Code Coverage Tools:** Services like [Codecov](https://codecov.io/) or [Coveralls](https://coveralls.io/) give you badges to show your test coverage percentage. +- **Code Coverage Tools:** Services like [Codecov](https://codecov.io/) or + [Coveralls](https://coveralls.io/) give you badges to show your test + coverage percentage. -- **Package Registries:** If your project is a package, registries like [npm](https://www.npmjs.com/), [PyPI](https://pypi.org/), [RubyGems](https://rubygems.org/), etc., offer badges to show the latest version, number of downloads, and more. +- **Package Registries:** If your project is a package, registries like + [npm](https://www.npmjs.com/), [PyPI](https://pypi.org/), + [RubyGems](https://rubygems.org/), etc., offer badges to show the latest + version, number of downloads, and more. -[Shields.io](https://shields.io/) is a great one-stop-shop that can create badges for all of the services above and many more, all with a consistent style. It can also be used to create completely custom badges. +[Shields.io](https://shields.io/) is a great one-stop-shop that can create +badges for all of the services above and many more, all with a consistent +style. +It can also be used to create completely custom badges. ## Common Badge Categories -Here are some of the most common categories of badges you might see in a project's `README.md`. +Here are some of the most common categories of badges you might see in a +project's `README.md`. ### Build Status -These badges show the status of your continuous integration (CI) builds. This is one of the most important badges as it tells contributors whether the project is currently in a working state. +These badges show the status of your continuous integration (CI) builds. +This is one of the most important badges as it tells contributors whether the +project is currently in a working state. **GitHub Actions** @@ -78,21 +102,30 @@ It's a good practice to include a badge for your project's license. ## How many badges is too many? -While badges are useful, having too many can clutter your `README.md` and make it difficult to read. A good rule of thumb is to include badges that are most relevant to your project and its contributors. +While badges are useful, having too many can clutter your `README.md` and make +it difficult to read. +A good rule of thumb is to include badges that are most relevant to your +project and its contributors. Consider these questions when deciding which badges to include: -- **Is it important for contributors to see this information at a glance?** (e.g., build status, license) -- **Does this badge provide a link to a useful resource?** (e.g., documentation, releases) -- **Does this badge add value to the project?** (e.g., code coverage, version) +- **Is it important for contributors to see this information at a glance?** + (e.g., build status, license) +- **Does this badge provide a link to a useful resource?** (e.g., + documentation, releases) +- **Does this badge add value to the project?** (e.g., code coverage, + version) -If the answer to these questions is "yes," then the badge is probably worth including. +If the answer to these questions is "yes," then the badge is probably worth +including. ## Custom Badges -You can also create your own custom badges using Shields.io. This is useful for linking to things that don't have a pre-made badge. +You can also create your own custom badges using Shields.io. +This is useful for linking to things that don't have a pre-made badge. -For example, you could create a badge to link to your project's documentation: +For example, you could create a badge to link to your project's +documentation: [![Documentation](https://img.shields.io/badge/documentation-yes-brightgreen.svg)](./docs/README.md) @@ -100,4 +133,5 @@ For example, you could create a badge to link to your project's documentation: [![Documentation](https://img.shields.io/badge/documentation-yes-brightgreen.svg)](./docs/README.md) ``` -You can create your own badges by visiting the [Shields.io](https://shields.io/) website and using their badge creation tool. +You can create your own badges by visiting the +[Shields.io](https://shields.io/) website and using their badge creation tool. diff --git a/docs/project.launch-checklist.md b/docs/project.launch-checklist.md index 17918c0..eeea86c 100644 --- a/docs/project.launch-checklist.md +++ b/docs/project.launch-checklist.md @@ -1,6 +1,7 @@ # Project Launch Checklist -Launching a new open-source project can be a daunting task. This checklist is designed to help you ensure a smooth and successful launch. +Launching a new open-source project can be a daunting task. +This checklist is designed to help you ensure a smooth and successful launch. ## Pre-Launch @@ -11,8 +12,10 @@ This is the phase where you prepare your project for its public debut. - [ ] Finalize initial feature set for `v1.0.0`. - [ ] Write comprehensive tests and ensure they are all passing. - [ ] Set up CI/CD workflows for testing and linting. -- [ ] Polish the codebase: remove commented-out code, fix typos, and ensure consistent styling. -- [ ] Run a security audit (e.g., check dependencies for known vulnerabilities). +- [ ] Polish the codebase: remove commented-out code, fix typos, and ensure + consistent styling. +- [ ] Run a security audit (e.g., check dependencies for known + vulnerabilities). ### Documentation @@ -25,8 +28,10 @@ This is the phase where you prepare your project for its public debut. ### Community & Marketing - [ ] Prepare a blog post or announcement for the launch. -- [ ] Identify communities (e.g., Reddit, Hacker News, specific forums) where you will share your project. -- [ ] Create a project website or landing page (GitHub Pages is a great option). +- [ ] Identify communities (e.g., Reddit, Hacker News, specific forums) where + you will share your project. +- [ ] Create a project website or landing page (GitHub Pages is a great + option). - [ ] Set up social media accounts if desired. ## Launch Day @@ -34,18 +39,21 @@ This is the phase where you prepare your project for its public debut. The day you make your project public. - [ ] **Publish your code:** Make your GitHub repository public. -- [ ] **Push the `v1.0.0` tag:** This will trigger your automated release workflow. +- [ ] **Push the `v1.0.0` tag:** This will trigger your automated release + workflow. ```bash git tag -a v1.0.0 -m "Initial public release" git push origin main --tags ``` -- [ ] **Publish your announcement:** Share your blog post and post on your chosen communities. -- [ ] **Monitor for feedback:** Keep a close eye on GitHub issues, social media, and other channels for questions and bug reports. -- [ ] **Be responsive:** Engage with early adopters, answer questions, and thank them for their interest. +- [ ] **Monitor for feedback:** Keep a close eye on GitHub issues, social + media, and other channels for questions and bug reports. +- [ ] **Be responsive:** Engage with early adopters, answer questions, and + thank them for their interest. ## Post-Launch -The work doesn't stop after launch day. Now it's about building momentum. +The work doesn't stop after launch day. +Now it's about building momentum. ### Short-Term (First Week) @@ -58,8 +66,11 @@ The work doesn't stop after launch day. Now it's about building momentum. - [ ] Continue to be responsive to issues and pull requests. - [ ] Start working on the features planned for `v1.1.0`. -- [ ] Nurture your community by empowering contributors (see the [Community Building Guide](./community-building-guide.md)). +- [ ] Nurture your community by empowering contributors (see the + [Community Building Guide](./community-building-guide.md)). - [ ] Set up a regular release cadence. - [ ] Periodically review and update your documentation. -This checklist is a starting point. Feel free to adapt it to the specific needs of your project. Good luck with your launch! +This checklist is a starting point. +Feel free to adapt it to the specific needs of your project. +Good luck with your launch! diff --git a/docs/project.licensing.md b/docs/project.licensing.md index f847de4..131d377 100644 --- a/docs/project.licensing.md +++ b/docs/project.licensing.md @@ -1,20 +1,28 @@ # Licensing Information -This repository is distributed under the MIT License, the full text of which is available in the [`LICENSE`](../LICENSE) file. +This repository is distributed under the MIT License, the full text of which +is available in the [`LICENSE`](../LICENSE) file. ## What is the MIT License? -The MIT License is a permissive free software license originating at the Massachusetts Institute of Technology (MIT). In simple terms, it allows you to do almost anything you want with the code, including using it in proprietary software, as long as you include the original copyright and license notice in any copy of the software. +The MIT License is a permissive free software license originating at the +Massachusetts Institute of Technology (MIT). +In simple terms, it allows you to do almost anything you want with the code, +including using it in proprietary software, as long as you include the +original copyright and license notice in any copy of the software. [Learn more about the MIT License](https://choosealicense.com/licenses/mit/). ## How to Use the `LICENSE` File -The included [`LICENSE`](../LICENSE) file contains a copyright line for the `base` template itself: +The included [`LICENSE`](../LICENSE) file contains a copyright line for the +`base` template itself: `Copyright (c) 2025 Attogram Project` -When you create your own project from this template, you should **add your own copyright notice** on a new line directly below the existing one. Do not remove the original line. +When you create your own project from this template, you should **add your own +copyright notice** on a new line directly below the existing one. +Do not remove the original line. For example: @@ -23,8 +31,14 @@ Copyright (c) 2025 Attogram Project Copyright (c) [Your Year] [Your Name or Company] ``` -This ensures that attribution is preserved while allowing you to claim copyright on your own modifications and additions. +This ensures that attribution is preserved while allowing you to claim +copyright on your own modifications and additions. ### Can I Choose a Different License? -Yes. You are free to delete the contents of the `LICENSE` file and replace it with a different license of your choice. However, be aware that this may affect how others can use your project. The [Choose a License](https://choosealicense.com/) website from GitHub is an excellent resource for understanding and selecting a software license. +Yes. +You are free to delete the contents of the `LICENSE` file and replace it with +a different license of your choice. +However, be aware that this may affect how others can use your project. +The [Choose a License](https://choosealicense.com/) website from GitHub is an +excellent resource for understanding and selecting a software license. diff --git a/docs/project.security.md b/docs/project.security.md index 0cc9567..74a1dc7 100644 --- a/docs/project.security.md +++ b/docs/project.security.md @@ -1,30 +1,59 @@ # Security Best Practices for Maintainers -As an open-source maintainer, you have a responsibility to ensure your project is secure. This guide covers some fundamental security practices to protect both your project and its users. +As an open-source maintainer, you have a responsibility to ensure your +project is secure. +This guide covers some fundamental security practices to protect both your +project and its users. ## 1. Protect Your Accounts -Your personal accounts are the first line of defense. If a malicious actor gains access to your GitHub account, they can do significant damage to your projects. +Your personal accounts are the first line of defense. +If a malicious actor gains access to your GitHub account, they can do +significant damage to your projects. -- **Use a Strong, Unique Password:** Use a password manager to generate and store strong, unique passwords for every service you use. -- **Enable Two-Factor Authentication (2FA):** 2FA is the single most important thing you can do to secure your accounts. Enable it on your GitHub account, your email account, and your package manager accounts (e.g., npm). +- **Use a Strong, Unique Password:** Use a password manager to generate and + store strong, unique passwords for every service you use. +- **Enable Two-Factor Authentication (2FA):** 2FA is the single most + important thing you can do to secure your accounts. + Enable it on your GitHub account, your email account, and your package + manager accounts (e.g., npm). ## 2. Manage Dependencies Securely -Modern software projects rely heavily on third-party dependencies. A vulnerability in one of your dependencies is a vulnerability in your project. +Modern software projects rely heavily on third-party dependencies. +A vulnerability in one of your dependencies is a vulnerability in your +project. -- **Enable Dependabot:** GitHub's Dependabot automatically scans your dependencies for known vulnerabilities and creates pull requests to update them to a secure version. This is enabled by default in this repository. -- **Review Dependencies:** When adding a new dependency, consider its popularity, maintenance status, and whether it has a good security track record. -- **Lock Your Dependencies:** Use a lock file (e.g., `package-lock.json`, `yarn.lock`) to ensure that you are using the exact same version of each dependency in every environment. +- **Enable Dependabot:** GitHub's Dependabot automatically scans your + dependencies for known vulnerabilities and creates pull requests to update + them to a secure version. + This is enabled by default in this repository. +- **Review Dependencies:** When adding a new dependency, consider its + popularity, maintenance status, and whether it has a good security track + record. +- **Lock Your Dependencies:** Use a lock file (e.g., `package-lock.json`, + `yarn.lock`) to ensure that you are using the exact same version of each + dependency in every environment. ## 3. Handle Security Reports Responsibly -You need a clear process for how a security researcher can report a vulnerability to you privately. +You need a clear process for how a security researcher can report a +vulnerability to you privately. -- **Create a `SECURITY.md` file:** This file, located in the `.github` directory, should explain how to report a security vulnerability. This repository includes a template [`SECURITY.md`](../.github/SECURITY.md) to get you started. -- **Use Private Vulnerability Reporting:** GitHub provides a feature for privately reporting vulnerabilities. This allows you to discuss and fix a vulnerability in a temporary private fork before it's announced to the public. -- **Be Responsive:** When you receive a security report, acknowledge it promptly. Keep the reporter informed of your progress. -- **Disclose Responsibly:** Once you have a fix, you should disclose the vulnerability. This typically involves: +- **Create a `SECURITY.md` file:** This file, located in the `.github` + directory, should explain how to report a security vulnerability. + This repository includes a template [`SECURITY.md`](../.github/SECURITY.md) + to get you started. +- **Use Private Vulnerability Reporting:** GitHub provides a feature for + privately reporting vulnerabilities. + This allows you to discuss and fix a vulnerability in a temporary private + fork before it's announced to the public. +- **Be Responsive:** When you receive a security report, acknowledge it + promptly. + Keep the reporter informed of your progress. +- **Disclose Responsibly:** Once you have a fix, you should disclose the + vulnerability. + This typically involves: - Publishing a security advisory. - Releasing a new version with the fix. - Requesting a CVE (Common Vulnerabilities and Exposures) identifier. @@ -33,8 +62,16 @@ You need a clear process for how a security researcher can report a vulnerabilit Your CI/CD workflows can be a target for attackers. -- **Be Cautious with Third-Party Actions:** Only use GitHub Actions from trusted creators. Pin actions to a specific commit SHA rather than a branch name to prevent malicious code from being injected. -- **Limit Permissions:** Grant your workflows only the minimum permissions they need to do their job. -- **Manage Secrets:** Use [GitHub Actions secrets](./secrets-management.md) to store and use credentials. Never hardcode them in your workflow files. +- **Be Cautious with Third-Party Actions:** Only use GitHub Actions from + trusted creators. + Pin actions to a specific commit SHA rather than a branch name to prevent + malicious code from being injected. +- **Limit Permissions:** Grant your workflows only the minimum permissions + they need to do their job. +- **Manage Secrets:** Use [GitHub Actions secrets](./secrets-management.md) + to store and use credentials. + Never hardcode them in your workflow files. -Security is an ongoing process, not a one-time checklist. By adopting these best practices, you can significantly improve the security posture of your open-source project and build trust with your users. +Security is an ongoing process, not a one-time checklist. +By adopting these best practices, you can significantly improve the security +posture of your open-source project and build trust with your users. diff --git a/docs/project.standard-files.md b/docs/project.standard-files.md index c4d0746..df4d5d8 100644 --- a/docs/project.standard-files.md +++ b/docs/project.standard-files.md @@ -1,27 +1,41 @@ # Standard Repository Files -This document explains the purpose of the standard, language-agnostic configuration files included in this repository. +This document explains the purpose of the standard, language-agnostic +configuration files included in this repository. ## [`.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`). +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) -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. +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) -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. +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) -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. +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). diff --git a/docs/project.template-repo.md b/docs/project.template-repo.md index e7ac34f..fd770ed 100644 --- a/docs/project.template-repo.md +++ b/docs/project.template-repo.md @@ -1,10 +1,14 @@ # Maintaining `base` as a Template Repository -This document is for maintainers of the `base` repository. It outlines the best practices and administrative steps required to ensure this repository functions correctly as a [GitHub Template](https://docs.github.com/en/repositories/creating-a-repository-on-github/creating-a-repository-from-a-template). +This document is for maintainers of the `base` repository. +It outlines the best practices and administrative steps required to ensure this +repository functions correctly as a +[GitHub Template](https://docs.github.com/en/repositories/creating-a-repository-on-github/creating-a-repository-from-a-template). ## GitHub Settings -Ensure the following setting is enabled in the repository's main settings page (`Settings` > `General`): +Ensure the following setting is enabled in the repository's main settings page +(`Settings` > `General`): - [x] **Template repository** @@ -12,17 +16,29 @@ This allows users to generate new repositories from this one. ## Writing Content for the Template -When adding or modifying files, remember that they will be copied verbatim into new repositories. - -- **Use Placeholders:** For project-specific information like copyright notices or contact information, use clear placeholders like `[year] [fullname]` or `[INSERT CONTACT METHOD]`. -- **Write Instructional Content:** Files like [`CONTRIBUTING.md`](../CONTRIBUTING.md) and [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) should not be prescriptive. Instead, they should guide the end-user on how to create their own versions of these files. -- **Relative Links:** Use relative links for all in-repository links (e.g., `[link text](./path/to/file.md)`) to ensure they work correctly in the generated repositories. +When adding or modifying files, remember that they will be copied verbatim into +new repositories. + +- **Use Placeholders:** For project-specific information like copyright notices + or contact information, use clear placeholders like `[year] [fullname]` or + `[INSERT CONTACT METHOD]`. +- **Write Instructional Content:** Files like + [`CONTRIBUTING.md`](../CONTRIBUTING.md) and + [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) should not be prescriptive. + Instead, they should guide the end-user on how to create their own versions + of these files. +- **Relative Links:** Use relative links for all in-repository links (e.g., + `[link text](./path/to/file.md)`) to ensure they work correctly in the + generated repositories. ## Maintainer Checklist Before tagging a new release of `base`, review the following: -- [ ] All documentation in the [`docs/`](./) directory is up-to-date with the latest changes. -- [ ] All workflows in [`.github/workflows/`](../.github/workflows/) are tested and functioning. +- [ ] All documentation in the [`docs/`](./) directory is up-to-date with the + latest changes. +- [ ] All workflows in [`.github/workflows/`](../.github/workflows/) are + tested and functioning. - [ ] All placeholder files are clear and provide good guidance. -- [ ] The [`AGENTS.md`](../AGENTS.md) file has been updated to reflect any changes that would affect AI assistants. +- [ ] The [`AGENTS.md`](../AGENTS.md) file has been updated to reflect any + changes that would affect AI assistants. diff --git a/docs/project.versioning.md b/docs/project.versioning.md index 6a8e7b4..90f0969 100644 --- a/docs/project.versioning.md +++ b/docs/project.versioning.md @@ -1,13 +1,21 @@ # Versioning and Release Management -A well-defined versioning and release strategy is crucial for any professional software project. It provides clarity for consumers of your software and helps maintainers keep track of changes. This guide outlines best practices using Semantic Versioning (SemVer) and GitHub's automated release features. +A well-defined versioning and release strategy is crucial for any professional +software project. +It provides clarity for consumers of your software and helps maintainers keep +track of changes. +This guide outlines best practices using Semantic Versioning (SemVer) and +GitHub's automated release features. ## Semantic Versioning (SemVer) -Semantic Versioning is a widely adopted versioning scheme that gives meaning to version numbers. A version number is composed of three parts: `MAJOR.MINOR.PATCH`. +Semantic Versioning is a widely adopted versioning scheme that gives meaning +to version numbers. +A version number is composed of three parts: `MAJOR.MINOR.PATCH`. - **MAJOR** version: Incremented for incompatible API changes. -- **MINOR** version: Incremented for adding functionality in a backward-compatible manner. +- **MINOR** version: Incremented for adding functionality in a + backward-compatible manner. - **PATCH** version: Incremented for backward-compatible bug fixes. For example, `v1.2.3` means: @@ -16,36 +24,57 @@ For example, `v1.2.3` means: - `2`: Minor version 2 - `3`: Patch version 3 -Adhering to SemVer helps users understand the impact of upgrading and allows them to specify dependency versions safely. +Adhering to SemVer helps users understand the impact of upgrading and allows +them to specify dependency versions safely. ### Pre-releases -For versions that are not yet stable, you can use pre-release tags, such as `1.0.0-alpha.1`, `1.0.0-beta.2`, or `1.0.0-rc.1`. These are useful for testing and getting feedback before a final release. +For versions that are not yet stable, you can use pre-release tags, such as +`1.0.0-alpha.1`, `1.0.0-beta.2`, or `1.0.0-rc.1`. +These are useful for testing and getting feedback before a final release. ## Automated Releases with GitHub -This repository is configured with a GitHub Actions workflow that automates the process of creating a GitHub Release when you push a new tag. +This repository is configured with a GitHub Actions workflow that automates +the process of creating a GitHub Release when you push a new tag. ### How it Works -1. **Tag a Commit:** When your `main` branch is ready for a release, you create a git tag pointing to the commit you want to release. The tag name **must** follow Semantic Versioning (e.g., `v1.0.0`, `v2.3.1`). +1. **Tag a Commit:** When your `main` branch is ready for a release, you + create a git tag pointing to the commit you want to release. + The tag name **must** follow Semantic Versioning (e.g., `v1.0.0`, + `v2.3.1`). ```bash git tag -a v1.0.0 -m "Initial release" git push origin v1.0.0 ``` -2. **Workflow Trigger:** Pushing the tag to the repository triggers the [`.github/release-on-tag.yml`](../.github/workflows/release-on-tag.yml) workflow. +2. **Workflow Trigger:** Pushing the tag to the repository triggers the + [`.github/release-on-tag.yml`](../.github/workflows/release-on-tag.yml) + workflow. -3. **Automated Release Notes:** The workflow automatically generates release notes based on the titles of the pull requests merged since the last release. It categorizes them into sections like "Features," "Bug Fixes," and "Maintenance." +3. **Automated Release Notes:** The workflow automatically generates release + notes based on the titles of the pull requests merged since the last + release. + It categorizes them into sections like "Features," "Bug Fixes," and + "Maintenance." -4. **Create Release:** The workflow creates a new GitHub Release with the tag, the generated release notes, and any build artifacts you've configured. +4. **Create Release:** The workflow creates a new GitHub Release with the + tag, the generated release notes, and any build artifacts you've + configured. ### Customizing Release Notes -You can customize the title and body of the release notes by editing the following files: +You can customize the title and body of the release notes by editing the +following files: -- [`.github/RELEASE_TITLE.txt`](../.github/RELEASE_TITLE.txt): A one-line title for your release. -- [`.github/RELEASE_BODY.md`](../.github/RELEASE_BODY.md): A markdown file where you can add introductory text or other custom content to the release notes. +- [`.github/RELEASE_TITLE.txt`](../.github/RELEASE_TITLE.txt): A one-line + title for your release. +- [`.github/RELEASE_BODY.md`](../.github/RELEASE_BODY.md): A markdown file + where you can add introductory text or other custom content to the release + notes. -By combining Semantic Versioning with automated release workflows, you can maintain a professional, consistent, and low-friction release process for your project. +By combining Semantic Versioning with automated release workflows, you can +maintain a professional, consistent, and low-friction release process for your +project. diff --git a/docs/publishing.github-pages.md b/docs/publishing.github-pages.md index dce15c4..f3c6cde 100644 --- a/docs/publishing.github-pages.md +++ b/docs/publishing.github-pages.md @@ -1,27 +1,48 @@ # GitHub Pages Site -This repository is configured to use [GitHub Pages](https://pages.github.com/) to host a simple, clean website for the project. +This repository is configured to use [GitHub Pages](https://pages.github.com/) +to host a simple, clean website for the project. ## Initial Setup -Before the workflow can deploy your site, you must configure your repository to use GitHub Actions for GitHub Pages. This is a one-time setup step that connects your repository's Pages settings to the `pages.yml` workflow included in this template. +Before the workflow can deploy your site, you must configure your repository +to use GitHub Actions for GitHub Pages. +This is a one-time setup step that connects your repository's Pages settings +to the `pages.yml` workflow included in this template. -1. **Navigate to Repository Settings:** Go to the main page of your repository and click on the **Settings** tab. +1. **Navigate to Repository Settings:** Go to the main page of your + repository and click on the **Settings** tab. 2. **Select Pages:** In the left-hand sidebar, click on **Pages**. -3. **Set the Deployment Source:** Under the "Build and deployment" section, you will see a **Source** option. Select **"GitHub Actions"** from the dropdown menu. +3. **Set the Deployment Source:** Under the "Build and deployment" section, + you will see a **Source** option. + Select **"GitHub Actions"** from the dropdown menu. -After you select "GitHub Actions", the UI may present you with suggestions for common workflows (e.g., "GitHub Pages Jekyll", "Static HTML"). **You can ignore these suggestions.** This repository already contains a custom, pre-configured workflow ([`.github/workflows/pages.yml`](../.github/workflows/pages.yml)) that will be used automatically. +After you select "GitHub Actions", the UI may present you with suggestions +for common workflows (e.g., "GitHub Pages Jekyll", "Static HTML"). +**You can ignore these suggestions.** +This repository already contains a custom, pre-configured workflow +([`.github/workflows/pages.yml`](../.github/workflows/pages.yml)) that will +be used automatically. -> **Note:** If you do not perform this setup step, the [`pages.yml`](../.github/workflows/pages.yml) workflow will fail with a "Get Pages site failed" or "HttpError: Not Found" error. +> **Note:** If you do not perform this setup step, the +> [`pages.yml`](../.github/workflows/pages.yml) workflow will fail with a +> "Get Pages site failed" or "HttpError: Not Found" error. ## How It Works -The site is built and deployed by the [`.github/workflows/pages.yml`](../.github/workflows/pages.yml) workflow. Here's a summary of the process: - -1. **Trigger:** The workflow runs automatically on every push to the `main` branch. -2. **Jekyll Build:** It uses the standard `jekyll-build-pages` GitHub Action to build a static website. -3. **Homepage:** It is configured to use the root [`README.md`](../README.md) file as the content for the homepage (`index.html`) of the site. -4. **Styling:** The [`_config.yml`](../_config.yml) file in the root of the repository specifies the `jekyll-theme-primer` theme, which gives the site the standard GitHub look and feel. +The site is built and deployed by the +[`.github/workflows/pages.yml`](../.github/workflows/pages.yml) workflow. +Here's a summary of the process: + +1. **Trigger:** The workflow runs automatically on every push to the `main` + branch. +2. **Jekyll Build:** It uses the standard `jekyll-build-pages` GitHub Action + to build a static website. +3. **Homepage:** It is configured to use the root [`README.md`](../README.md) + file as the content for the homepage (`index.html`) of the site. +4. **Styling:** The [`_config.yml`](../_config.yml) file in the root of the + repository specifies the `jekyll-theme-primer` theme, which gives the + site the standard GitHub look and feel. 5. **Deployment:** The built static site is then deployed to GitHub Pages. ## Accessing the Site @@ -30,4 +51,5 @@ After the first push to `main`, the site will be available at a URL like: `https://.github.io//` -You can also find the URL in the "Pages" section of your repository's settings. +You can also find the URL in the "Pages" section of your repository's +settings. diff --git a/docs/publishing.html.md b/docs/publishing.html.md index 1391b1e..99aaf11 100644 --- a/docs/publishing.html.md +++ b/docs/publishing.html.md @@ -1,33 +1,46 @@ # Advanced Publishing: HTML, Previews, and More -This guide covers the more advanced features of the publishing platform, including using HTML, previewing your site locally, and understanding the platform's limitations. +This guide covers the more advanced features of the publishing platform, +including using HTML, previewing your site locally, and understanding the +platform's limitations. ## Using HTML for More Control -While Markdown is easy to use, you can also use standard HTML (`.html`) files for your pages. This is useful for complex layouts that require specific HTML structures or CSS classes. +While Markdown is easy to use, you can also use standard HTML (`.html`) files +for your pages. +This is useful for complex layouts that require specific HTML structures or +CSS classes. -You can create new `.html` files or add existing ones to the repository, and they will be published as pages on your site. +You can create new `.html` files or add existing ones to the repository, and +they will be published as pages on your site. -While most HTML tags are stripped for security, GitHub Pages allows a "whitelist" of safe tags for advanced formatting. +While most HTML tags are stripped for security, GitHub Pages allows a +"whitelist" of safe tags for advanced formatting. -A great example is creating a collapsible section using `
` and ``. +A great example is creating a collapsible section using `
` and +``. ```html
Click here to see the details! - This content is hidden until you click the summary. You can put any Markdown - content in here, including lists, code blocks, or images. + This content is hidden until you click the summary. + You can put any Markdown content in here, including lists, code blocks, or + images.
``` -Other useful HTML tags that are generally allowed include `` for subscript, `` for superscript, and `` for styling keyboard inputs like Ctrl+C. +Other useful HTML tags that are generally allowed include `` for +subscript, `` for superscript, and `` for +styling keyboard inputs like Ctrl+C. ## Advanced Theming ### Using Other Themes -You are not limited to the themes supported by default. Using the `remote_theme` option in `_config.yml`, you can use almost any public Jekyll theme hosted on GitHub. +You are not limited to the themes supported by default. +Using the `remote_theme` option in `_config.yml`, you can use almost any +public Jekyll theme hosted on GitHub. ```yaml # remote_theme: owner/repository-name @@ -36,10 +49,12 @@ remote_theme: jekyll/minima ### Customizing a Theme's CSS -If you want to add your own custom styles without creating a whole new theme, you can override the theme's CSS. +If you want to add your own custom styles without creating a whole new theme, +you can override the theme's CSS. 1. Create a file named `/assets/css/style.scss`. -2. Add the following lines to the top of the file. This imports the theme's default stylesheet. +2. Add the following lines to the top of the file. + This imports the theme's default stylesheet. ```scss --- @@ -54,18 +69,34 @@ If you want to add your own custom styles without creating a whole new theme, yo ## Understanding the Limitations -GitHub Pages is a powerful tool, but it's important to understand its limitations. +GitHub Pages is a powerful tool, but it's important to understand its +limitations. -- **Static Sites Only:** This is the most important limitation. GitHub Pages cannot run server-side code (like PHP, Python, or a database). It can only serve static files: HTML, CSS, JavaScript, images, etc. This means you cannot have features like a user login system, a shopping cart, or a server-side contact form. +- **Static Sites Only:** This is the most important limitation. + GitHub Pages cannot run server-side code (like PHP, Python, or a + database). + It can only serve static files: HTML, CSS, JavaScript, images, etc. + This means you cannot have features like a user login system, a shopping + cart, or a server-side contact form. -- **Usage Limits:** For repositories on the free plan, GitHub Pages has some soft limits: +- **Usage Limits:** For repositories on the free plan, GitHub Pages has some + soft limits: - **Size:** Your repository should ideally stay under 1GB. - - **Bandwidth:** Your site has a soft limit of 100GB of bandwidth per month. - - **Builds:** Your site will be rebuilt up to 10 times per hour. Pushing many small commits in a short period might cause some builds to be skipped. - -- **No Custom Jekyll Plugins:** GitHub Pages only supports a specific list of Jekyll plugins. You cannot use custom or third-party plugins that are not on [this list](https://pages.github.com/versions/). - -- **Site Visibility:** If your repository is public, your GitHub Pages site will be public. If your repository is private, your site will also be public unless you have a paid GitHub plan (Pro, Team, or Enterprise). + - **Bandwidth:** Your site has a soft limit of 100GB of bandwidth per + month. + - **Builds:** Your site will be rebuilt up to 10 times per hour. + Pushing many small commits in a short period might cause some builds to be + skipped. + +- **No Custom Jekyll Plugins:** GitHub Pages only supports a specific list of + Jekyll plugins. + You cannot use custom or third-party plugins that are not on + [this list](https://pages.github.com/versions/). + +- **Site Visibility:** If your repository is public, your GitHub Pages site + will be public. + If your repository is private, your site will also be public unless you have + a paid GitHub plan (Pro, Team, or Enterprise). --- @@ -73,9 +104,14 @@ GitHub Pages is a powerful tool, but it's important to understand its limitation ### Previewing Your Site Locally -The default workflow is to push changes and wait for GitHub to publish them. For larger changes, you may want to preview your site on your own computer before publishing. +The default workflow is to push changes and wait for GitHub to publish them. +For larger changes, you may want to preview your site on your own computer +before publishing. -This requires installing Ruby and Jekyll. While the setup can be technical, the benefit is that you can run a local web server that behaves exactly like GitHub Pages and see your changes instantly at `http://localhost:4000`. +This requires installing Ruby and Jekyll. +While the setup can be technical, the benefit is that you can run a local web +server that behaves exactly like GitHub Pages and see your changes instantly +at `http://localhost:4000`. To learn how to do this, follow the official guide from GitHub: @@ -83,9 +119,13 @@ To learn how to do this, follow the official guide from GitHub: ### Creating a Navigation Menu -Many themes allow you to create a persistent navigation menu at the top of your site. The implementation details depend on the theme, but it is often configured in the `_config.yml` file. +Many themes allow you to create a persistent navigation menu at the top of +your site. +The implementation details depend on the theme, but it is often configured +in the `_config.yml` file. -For example, the popular "Minima" theme looks for a `header_pages` array in your `_config.yml`: +For example, the popular "Minima" theme looks for a `header_pages` array in +your `_config.yml`: ```yaml # In _config.yml @@ -94,6 +134,9 @@ header_pages: - contact.md ``` -The default `primer` theme does not support this feature out-of-the-box. To add a navigation menu, you will need to switch to a different theme or add your own custom HTML layout. +The default `primer` theme does not support this feature out-of-the-box. +To add a navigation menu, you will need to switch to a different theme or add +your own custom HTML layout. -**Always check the documentation for your chosen theme** to see what navigation features it supports and how to configure them. +**Always check the documentation for your chosen theme** to see what +navigation features it supports and how to configure them. diff --git a/docs/publishing.magic-links.md b/docs/publishing.magic-links.md index 042ac86..a610c22 100644 --- a/docs/publishing.magic-links.md +++ b/docs/publishing.magic-links.md @@ -1,12 +1,19 @@ # Publishing with Magic Links -"Magic Links" are special URLs that can pre-fill a new file in a GitHub repository with template content. This is a powerful way to encourage community contributions by making it easy for users to submit content in a structured format, such as a bug report, a testimonial, or a new blog post. +"Magic Links" are special URLs that can pre-fill a new file in a GitHub +repository with template content. +This is a powerful way to encourage community contributions by making it easy +for users to submit content in a structured format, such as a bug report, a +testimonial, or a new blog post. ## How They Work -The link is a standard URL used to create a new file on GitHub, but it is enhanced with query parameters to specify a filename and pre-fill its content. +The link is a standard URL used to create a new file on GitHub, but it is +enhanced with query parameters to specify a filename and pre-fill its +content. -Here is a generic example of what the Markdown for a magic link might look like: +Here is a generic example of what the Markdown for a magic link might look +like: ```markdown [Click Here to Add a New Item](https://github.com/{OWNER}/{REPO}/new/{BRANCH}/?filename={PATH_TO_FILE}&value={URL_ENCODED_CONTENT}) @@ -14,12 +21,17 @@ Here is a generic example of what the Markdown for a magic link might look like: ### Key Parameters -- `filename`: This specifies the directory and name of the file to be created. You can use placeholders to guide users, for example: `_posts/YYYY-MM-DD-your-title.md`. This encourages good file naming conventions. -- `value`: This contains the URL-encoded content that will pre-fill the new file. +- `filename`: This specifies the directory and name of the file to be created. + You can use placeholders to guide users, for example: + `_posts/YYYY-MM-DD-your-title.md`. + This encourages good file naming conventions. +- `value`: This contains the URL-encoded content that will pre-fill the new + file. ## Deconstructing the `value` Parameter -The `value` parameter is the core of the magic link. It's your template, but URL-encoded. +The `value` parameter is the core of the magic link. +It's your template, but URL-encoded. Here is an example of a decoded template for a simple blog post: @@ -39,23 +51,38 @@ author: "[Your Name or GitHub Username]" 2. Link to them with `![Image description](./your-image-name.png)` ``` -This example uses a standard Jekyll post format with YAML front matter. The placeholders guide the user on what to fill in. +This example uses a standard Jekyll post format with YAML front matter. +The placeholders guide the user on what to fill in. ## How to Create Your Own Magic Link -1. **Write Your Template Content:** In a text editor, write the exact content you want to pre-fill for the user. Use clear placeholders like `[REPLACE THIS]` to indicate where they should add their own information. - -2. **URL-Encode the Content:** Your template content must be URL-encoded to be safely included in the link. This process converts special characters (like spaces, newlines, and symbols) into a format that can be transmitted over the internet. There are many free online tools available for URL encoding. Simply paste your template content into one of these tools to get the encoded version. - -3. **Construct the Final URL:** Assemble the link by combining the base URL and your parameters. +1. **Write Your Template Content:** In a text editor, write the exact + content you want to pre-fill for the user. + Use clear placeholders like `[REPLACE THIS]` to indicate where they should + add their own information. + +2. **URL-Encode the Content:** Your template content must be URL-encoded to + be safely included in the link. + This process converts special characters (like spaces, newlines, and + symbols) into a format that can be transmitted over the internet. + There are many free online tools available for URL encoding. + Simply paste your template content into one of these tools to get the + encoded version. + +3. **Construct the Final URL:** Assemble the link by combining the base URL + and your parameters. - **Base URL:** `https://github.com/{OWNER}/{REPO}/new/{BRANCH}/` - - Replace `{OWNER}`, `{REPO}`, and `{BRANCH}` with your repository's information. + - Replace `{OWNER}`, `{REPO}`, and `{BRANCH}` with your repository's + information. - **Filename:** `?filename=path/to/your/new-file.md` - Define the path and name for the new file. - **Value:** `&value={YOUR_ENCODED_CONTENT}` - Paste your URL-encoded template content here. -4. **Create the Markdown Link:** For easy use, embed your final URL into a Markdown link. Using `` tags can make the link appear more like a button, which can improve user experience. +4. **Create the Markdown Link:** For easy use, embed your final URL into a + Markdown link. + Using `` tags can make the link appear more like a button, which can + improve user experience. ```markdown [Click Here to Contribute](YOUR_FINAL_URL) diff --git a/docs/publishing.markdown.md b/docs/publishing.markdown.md index 8b6a5eb..b6b822d 100644 --- a/docs/publishing.markdown.md +++ b/docs/publishing.markdown.md @@ -1,10 +1,14 @@ # Publishing with Markdown -This repository is pre-configured to act as a simple, powerful, and free website publishing platform using GitHub Pages. This guide walks you through how to use it to create and manage your own site. +This repository is pre-configured to act as a simple, powerful, and free +website publishing platform using GitHub Pages. +This guide walks you through how to use it to create and manage your own site. ## Part 1: Choosing Your Website's Design -Your website's look and feel is controlled by a "theme". This repository uses Jekyll, a static site generator, which has great support for themes. +Your website's look and feel is controlled by a "theme". +This repository uses Jekyll, a static site generator, which has great support +for themes. ### How to Change Your Theme @@ -12,12 +16,15 @@ You can change your website's theme with a single line of code. 1. Open the `_config.yml` file in the root of your repository. 2. You will see a line: `theme: jekyll-theme-primer`. -3. To change the theme, simply replace `jekyll-theme-primer` with the name of another supported theme. For example: `theme: jekyll-theme-minimal`. +3. To change the theme, simply replace `jekyll-theme-primer` with the name + of another supported theme. + For example: `theme: jekyll-theme-minimal`. 4. Commit the change, and your site will be rebuilt with the new theme. ### Supported Themes -GitHub Pages officially supports a number of themes. You can preview them by visiting their repositories. +GitHub Pages officially supports a number of themes. +You can preview them by visiting their repositories. | Theme Name | How to Use It (`_config.yml`) | Preview Link | | :----------- | :--------------------------------- | :------------------------------------------------------------- | @@ -41,22 +48,31 @@ GitHub Pages officially supports a number of themes. You can preview them by vis Publishing is as simple as editing text files. -1. **Edit or Create Files:** Edit an existing Markdown (`.md`) file or create a new one. +1. **Edit or Create Files:** Edit an existing Markdown (`.md`) file or + create a new one. 2. **Commit and Push:** Save and push your changes to the `main` branch. -3. **Done!** The website will automatically rebuild and your changes will be live in a minute or two. +3. **Done!** The website will automatically rebuild and your changes will be + live in a minute or two. ### Homepage and Other Pages -- **Homepage:** The content of your site's homepage is the `README.md` file in the root of the repository. -- **Other Pages:** Any other `.md` file in your repository becomes a page on your site. For example, `contact.md` will be available at `your-site.com/contact`. +- **Homepage:** The content of your site's homepage is the `README.md` file + in the root of the repository. +- **Other Pages:** Any other `.md` file in your repository becomes a page on + your site. + For example, `contact.md` will be available at `your-site.com/contact`. ### Organizing Your Site -You can create folders to organize your content. A file at `docs/about.md` will be available at `your-site.com/docs/about`. +You can create folders to organize your content. +A file at `docs/about.md` will be available at `your-site.com/docs/about`. -To link between pages, use relative links in your Markdown. It's best to use paths relative to the current file (e.g., starting with `./` or `../`). +To link between pages, use relative links in your Markdown. +It's best to use paths relative to the current file (e.g., starting with +`./` or `../`). -For example, from your root `README.md`, you could link to a file in `docs` like this: +For example, from your root `README.md`, you could link to a file in `docs` +like this: ```markdown [Read our About page](./docs/about.md) @@ -64,7 +80,8 @@ For example, from your root `README.md`, you could link to a file in `docs` like ## Part 3: Advanced Formatting -Markdown is designed to be simple, but it has powerful features for creating rich content. +Markdown is designed to be simple, but it has powerful features for creating +rich content. ### Code Blocks with Syntax Highlighting @@ -97,10 +114,12 @@ function helloWorld() { ```markdown > [!NOTE] -> This is a note. It contains useful information users should know. +> This is a note. +> It contains useful information users should know. > [!WARNING] -> This is a warning. It advises about risks or negative outcomes. +> This is a warning. +> It advises about risks or negative outcomes. ``` ### Working with Images and Videos @@ -114,7 +133,9 @@ The standard Markdown syntax for an image is `![Alt Text](URL)`. #### Embedding Videos -You can't embed a video player directly, but you can create a clickable thumbnail that links to the video. Replace `YOUTUBE_VIDEO_ID_HERE` with your video's ID. +You can't embed a video player directly, but you can create a clickable +thumbnail that links to the video. +Replace `YOUTUBE_VIDEO_ID_HERE` with your video's ID. ```markdown [![Watch the video](https://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg)](https://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE) @@ -122,7 +143,8 @@ You can't embed a video player directly, but you can create a clickable thumbnai ### Page Titles and SEO -To set a custom title and description for a specific page, add a "front matter" block to the very top of your `.md` file. +To set a custom title and description for a specific page, add a "front +matter" block to the very top of your `.md` file. ```yaml --- diff --git a/docs/publishing.md b/docs/publishing.md index 73373ce..ef640bd 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -1,19 +1,33 @@ # Publishing Your Project -This repository is pre-configured to act as a simple, powerful, and free website publishing platform using GitHub Pages. There are several ways to create and manage content, from simple to advanced. +This repository is pre-configured to act as a simple, powerful, and free +website publishing platform using GitHub Pages. +There are several ways to create and manage content, from simple to advanced. This document provides an overview of the different methods you can use. ## Publishing Guides - **[Publishing with Markdown](./publishing.markdown.md)** - - This is the simplest way to get started. If you are new to web development or just want to write and publish with minimal fuss, start here. This guide covers creating pages, formatting text, adding images, and more, all using plain Markdown files. + - This is the simplest way to get started. + If you are new to web development or just want to write and publish with + minimal fuss, start here. + This guide covers creating pages, formatting text, adding images, and + more, all using plain Markdown files. - **[Advanced Publishing with HTML](./publishing.html.md)** - - For those who need more control over their site's layout and appearance, this guide explains how to use raw HTML files, customize your theme's CSS, and work with more advanced Jekyll features. It also covers the limitations of the platform. + - For those who need more control over their site's layout and appearance, + this guide explains how to use raw HTML files, customize your theme's CSS, + and work with more advanced Jekyll features. + It also covers the limitations of the platform. - **[Publishing with Magic Links](./publishing.magic-links.md)** - - This guide explains a powerful feature for community-driven sites. Learn how to create special URLs that can pre-fill a new file in your repository with template content, making it easy for users to contribute structured data like bug reports, testimonials, or blog posts. + - This guide explains a powerful feature for community-driven sites. + Learn how to create special URLs that can pre-fill a new file in your + repository with template content, making it easy for users to contribute + structured data like bug reports, testimonials, or blog posts. - **[GitHub Pages](./publishing.github-pages.md)** - - This document provides more detail on how the underlying GitHub Pages service works to automatically build and deploy your site whenever you push a change. + - This document provides more detail on how the underlying GitHub Pages + service works to automatically build and deploy your site whenever you + push a change. From c6a384177f2e12354edb234186e11e1f9b1d7e2f Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 5 Sep 2025 10:42:58 +0000 Subject: [PATCH 3/3] style: Format code with Prettier This commit applies formatting changes from Prettier to ensure a consistent code style. --- docs/project.launch-checklist.md | 16 ++++++++-------- docs/project.template-repo.md | 6 +++--- docs/publishing.html.md | 5 ++--- docs/updating.adding-base-to-existing-repo.md | 6 ++++-- ...ing.syncing-your-repo-when-base-is-updated.md | 4 ++-- 5 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/project.launch-checklist.md b/docs/project.launch-checklist.md index eeea86c..26272fd 100644 --- a/docs/project.launch-checklist.md +++ b/docs/project.launch-checklist.md @@ -13,9 +13,9 @@ This is the phase where you prepare your project for its public debut. - [ ] Write comprehensive tests and ensure they are all passing. - [ ] Set up CI/CD workflows for testing and linting. - [ ] Polish the codebase: remove commented-out code, fix typos, and ensure - consistent styling. + consistent styling. - [ ] Run a security audit (e.g., check dependencies for known - vulnerabilities). + vulnerabilities). ### Documentation @@ -29,9 +29,9 @@ This is the phase where you prepare your project for its public debut. - [ ] Prepare a blog post or announcement for the launch. - [ ] Identify communities (e.g., Reddit, Hacker News, specific forums) where - you will share your project. + you will share your project. - [ ] Create a project website or landing page (GitHub Pages is a great - option). + option). - [ ] Set up social media accounts if desired. ## Launch Day @@ -40,15 +40,15 @@ The day you make your project public. - [ ] **Publish your code:** Make your GitHub repository public. - [ ] **Push the `v1.0.0` tag:** This will trigger your automated release - workflow. + workflow. ```bash git tag -a v1.0.0 -m "Initial public release" git push origin main --tags ``` - [ ] **Monitor for feedback:** Keep a close eye on GitHub issues, social - media, and other channels for questions and bug reports. + media, and other channels for questions and bug reports. - [ ] **Be responsive:** Engage with early adopters, answer questions, and - thank them for their interest. + thank them for their interest. ## Post-Launch @@ -67,7 +67,7 @@ Now it's about building momentum. - [ ] Continue to be responsive to issues and pull requests. - [ ] Start working on the features planned for `v1.1.0`. - [ ] Nurture your community by empowering contributors (see the - [Community Building Guide](./community-building-guide.md)). + [Community Building Guide](./community-building-guide.md)). - [ ] Set up a regular release cadence. - [ ] Periodically review and update your documentation. diff --git a/docs/project.template-repo.md b/docs/project.template-repo.md index fd770ed..7beda21 100644 --- a/docs/project.template-repo.md +++ b/docs/project.template-repo.md @@ -36,9 +36,9 @@ new repositories. Before tagging a new release of `base`, review the following: - [ ] All documentation in the [`docs/`](./) directory is up-to-date with the - latest changes. + latest changes. - [ ] All workflows in [`.github/workflows/`](../.github/workflows/) are - tested and functioning. + tested and functioning. - [ ] All placeholder files are clear and provide good guidance. - [ ] The [`AGENTS.md`](../AGENTS.md) file has been updated to reflect any - changes that would affect AI assistants. + changes that would affect AI assistants. diff --git a/docs/publishing.html.md b/docs/publishing.html.md index 99aaf11..732d20c 100644 --- a/docs/publishing.html.md +++ b/docs/publishing.html.md @@ -24,9 +24,8 @@ A great example is creating a collapsible section using `
` and
Click here to see the details! - This content is hidden until you click the summary. - You can put any Markdown content in here, including lists, code blocks, or - images. + This content is hidden until you click the summary. You can put any Markdown + content in here, including lists, code blocks, or images.
``` diff --git a/docs/updating.adding-base-to-existing-repo.md b/docs/updating.adding-base-to-existing-repo.md index 9d7145c..c62b948 100644 --- a/docs/updating.adding-base-to-existing-repo.md +++ b/docs/updating.adding-base-to-existing-repo.md @@ -29,8 +29,8 @@ in your browser. - Click the "**<> Code**" button. - Go to the "**Codespaces**" tab. - Click "**Create codespace on [your-branch-name]**". - This will create a new development environment and open it in a new browser - tab. + This will create a new development environment and open it in a new browser + tab. 3. **Open the Terminal:** Once the Codespace has loaded, you will see a code editor and a file @@ -88,6 +88,7 @@ installed on their local machine. First, you need to add the `base` repository as a remote to your local Git repository. This allows you to fetch its branches and history. + ```bash git remote add base https://github.com/attogram/base.git ``` @@ -95,6 +96,7 @@ installed on their local machine. 2. **Fetch and Merge `base`:** Next, fetch the `base` repository's history and merge its `main` branch into your project's main branch. + ```bash git fetch base git merge base/main --allow-unrelated-histories diff --git a/docs/updating.syncing-your-repo-when-base-is-updated.md b/docs/updating.syncing-your-repo-when-base-is-updated.md index 49ba137..6ee5a8c 100644 --- a/docs/updating.syncing-your-repo-when-base-is-updated.md +++ b/docs/updating.syncing-your-repo-when-base-is-updated.md @@ -27,8 +27,8 @@ in your browser. - Click the "**<> Code**" button. - Go to the "**Codespaces**" tab. - Click "**Create codespace on [your-branch-name]**". - This will create a new development environment and open it in a new browser - tab. + This will create a new development environment and open it in a new browser + tab. 3. **Open the Terminal:** Once the Codespace has loaded, you will see a code editor and a file