diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..50349f4 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,11 @@ +{ + "name": "Base Template Dev Environment", + "dockerComposeFile": "../docker-compose.yml", + "service": "dev", + "workspaceFolder": "/workspace", + "customizations": { + "vscode": { + "extensions": ["ms-azuretools.vscode-docker", "eamodio.gitlens"] + } + } +} diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..f527827 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,6 @@ +.git +.github +docs +.vscode +.idea +*.md diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..9e6ecb3 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,13 @@ +# EditorConfig helps developers define and maintain consistent +# coding styles between different editors and IDEs. +# editorconfig.org + +root = true + +[*] +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +charset = utf-8 +indent_style = space +indent_size = 2 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6313b56 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto eol=lf diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..1089906 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,33 @@ +--- +name: Bug Report +about: Create a report to help us improve +title: "[BUG] " +labels: bug +assignees: "" +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: + +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + +- OS: [e.g. iOS] +- Browser [e.g. chrome, safari] +- Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..265faa6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ + + +### Description + +### Related Issue + +### Checklist + +- [ ] I have read the [CONTRIBUTING.md](CONTRIBUTING.md) document. +- [ ] My code follows the style guidelines of this project. +- [ ] I have added tests that prove my fix is effective or that my feature works. +- [ ] All new and existing tests passed. diff --git a/.github/RELEASE_BODY.md b/.github/RELEASE_BODY.md new file mode 100644 index 0000000..3e63765 --- /dev/null +++ b/.github/RELEASE_BODY.md @@ -0,0 +1,5 @@ +## New in ${TAG} + +- Add your release notes here. +- What are the new features? +- What bugs were fixed? diff --git a/.github/RELEASE_TEMPLATE.md b/.github/RELEASE_TEMPLATE.md new file mode 100644 index 0000000..1fb0590 --- /dev/null +++ b/.github/RELEASE_TEMPLATE.md @@ -0,0 +1,3 @@ + diff --git a/.github/RELEASE_TITLE.txt b/.github/RELEASE_TITLE.txt new file mode 100644 index 0000000..89453c1 --- /dev/null +++ b/.github/RELEASE_TITLE.txt @@ -0,0 +1 @@ +Release ${TAG} diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..6f6c8fe --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,7 @@ +# Security Policy + +This is a template repository. To create a security policy for your own project based on this template, you should create your own `SECURITY.md` file. + +This file should contain information about which versions of your project are supported with security updates and, most importantly, how to report a vulnerability. + +For detailed guidance on adding a security policy to your repository, please see the official [GitHub documentation](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository). diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..ec70b9a --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,26 @@ +name: Lint and Validate + +on: + push: + branches: ["main"] + pull_request: + branches: ["main"] + +jobs: + lint: + name: Lint Code Base + runs-on: ubuntu-latest + steps: + - name: Checkout Code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Install Prettier + run: npm install --global prettier + + - name: Run Prettier + run: prettier --check . diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..3cba0e5 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,50 @@ +name: Deploy GitHub Pages site + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/release-on-tag.yml b/.github/workflows/release-on-tag.yml new file mode 100644 index 0000000..2843363 --- /dev/null +++ b/.github/workflows/release-on-tag.yml @@ -0,0 +1,51 @@ +name: Create Release + +on: + push: + tags: + - "v*.*.*" + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Generate release notes + id: generate_notes + run: | + PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || git rev-list --max-parents=0 HEAD) + echo "Previous tag: $PREVIOUS_TAG" + + CHANGELOG=$(git log $PREVIOUS_TAG..HEAD --pretty=format:'* %s ([%h](https://github.com/${{ github.repository }}/commit/%H))') + + USER_BODY=$(sed "s/\${TAG}/${{ github.ref_name }}/g" .github/RELEASE_BODY.md) + + CHANGELOG_HEADER="## What's Changed" + DIFF_LINK="**Full Changelog**: https://github.com/${{ github.repository }}/compare/$PREVIOUS_TAG...${{ github.ref_name }}" + + { + echo "FINAL_BODY<> "$GITHUB_OUTPUT" + + - name: Create Release + uses: softprops/action-gh-release@v1 + with: + title: $(sed "s/\${TAG}/${{ github.ref_name }}/g" .github/RELEASE_TITLE.txt) + body: ${{ steps.generate_notes.outputs.FINAL_BODY }} + tag_name: ${{ github.ref_name }} + draft: false + prerelease: false diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..44bcabf --- /dev/null +++ b/.gitignore @@ -0,0 +1,19 @@ +# macOS +.DS_Store +.AppleDouble +.LSOverride + +# Windows +Thumbs.db +ehthumbs.db +ehthumbs_vista.db +*.[lL][oO][gG] +*.swo +*.swp + +# IDEs +.idea/ +.vscode/ +*.suo +*.user +*.sln.docstates diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..8f1866a --- /dev/null +++ b/.prettierrc @@ -0,0 +1,6 @@ +{ + "semi": true, + "singleQuote": false, + "tabWidth": 2, + "trailingComma": "es5" +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..168c2bc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# 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. + +## Core Philosophy + +The `base` repository serves as a high-quality, professional, and language-agnostic template for creating new software projects. Its core principles are: + +1. **Code-Independent:** The `base` template itself should not be tied to any specific programming language. The included Docker environment is based on Ubuntu and NGINX to be as generic as possible. +2. **Well-Documented:** Every feature, configuration file, and workflow should have corresponding documentation in the `/docs` directory. The goal is to leave no part of the repository unexplained. +3. **Guidance over Prescription:** For files like `CONTRIBUTING.md` or `LICENSE`, the template provides sensible defaults and guides the end-user on how to customize them, rather than enforcing a single choice. +4. **Automation:** The repository leverages GitHub Actions for CI, deployment, and releases to automate common developer tasks. + +## Repository Structure + +This is a breakdown of the most important files and directories in this repository: + +- **`.github/`**: Contains all GitHub-specific configurations. + - `workflows/`: Houses the GitHub Actions workflows. + - `ci.yml`: Lints configuration files for syntax and style. + - `pages.yml`: Deploys the documentation to GitHub Pages. + - `release-on-tag.yml`: Automates the creation of GitHub Releases from a git tag. + - `ISSUE_TEMPLATE/` & `PULL_REQUEST_TEMPLATE.md`: Templates for contributors. + - `RELEASE_TITLE.txt` & `RELEASE_BODY.md`: User-editable files for customizing release notes. + - `SECURITY.md`: A template for the user's security policy. + +- **`docs/`**: Contains all documentation for the project. Each major feature or component has its own corresponding `.md` file in this directory. + +- **`docker/`**: Contains the development environment. + - `Dockerfile`: Builds a generic Ubuntu + NGINX environment. + - `nginx.conf` & `html/index.html`: A simple web server that acts as a health check. + +- **`.devcontainer/`**: Configuration for GitHub Codespaces, making it easy to spin up the development environment in the cloud. + +- **Root Files**: + - `AGENTS.md`: This file! + - `README.md`: The main entry point, which links to the documentation. + - `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `LICENSE`: Standard community files, designed as templates for the end-user. + - `.gitignore`, `.editorconfig`, `.gitattributes`, `.prettierrc`: Configuration files for git and code styling. + - `docker-compose.yml`: Used to build and run the Docker-based development environment. + - `render.yaml`: Infrastructure-as-code for deploying the application to Render.com. + - `_config.yml`: Configuration for the Jekyll build for GitHub Pages. + +## Guidelines for Modification + +- **Maintain the Philosophy:** When adding or changing features, always adhere to the core principles, especially being code-independent. +- **Update Documentation:** If you change a feature, you **must** update its corresponding documentation in the `docs/` directory. If you add a new feature, you **must** create a new documentation file for it. +- **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! diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..4c2fce4 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,7 @@ +# Code of Conduct + +This is a template repository. To adopt a Code of Conduct for your own project, you should replace the contents of this file with a code of conduct that you are willing to enforce. + +A popular and widely used option is the [Contributor Covenant](https://www.contributor-covenant.org/). You can generate a markdown version of the covenant on their website and paste it into this file. + +Remember to update the `[INSERT CONTACT METHOD]` section with a private email address where violations can be reported. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e5f6775 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# How to Contribute + +This repository is a template. The contribution guide below is a generic placeholder. You should adapt it to the specific needs of your project. + +--- + +## Getting Started + +- Ensure you have read the project's `README.md`. +- If you are proposing a new feature, open an issue first to discuss it. + +## Making Changes + +1. **Fork the repository** on GitHub. +2. **Create a new branch** for your changes. + ```bash + git checkout -b feature/your-feature-name + ``` +3. **Make your changes** and commit them with a clear and descriptive message. +4. **Push your branch** to your fork on GitHub. + ```bash + git push origin feature/your-feature-name + ``` +5. **Open a Pull Request** to the `main` branch of the original repository. + +## Pull Request Checklist + +- My code follows the style guidelines of this project. +- I have added tests that prove my fix is effective or that my feature works. +- I have updated the documentation accordingly. + +--- + +_For more ideas on what to include in a contributing guide, check out the [Contributor Covenant's guide](https://www.contributor-covenant.org/docs/contributing-guidelines/)._ diff --git a/README.base.md b/README.base.md new file mode 100644 index 0000000..033606d --- /dev/null +++ b/README.base.md @@ -0,0 +1,5 @@ +# Base Repository Documentation + +This document serves as the main entry point for understanding the structure and philosophy of the `base` repository. + +_This is a placeholder file. You should expand this with detailed documentation about your project's architecture, conventions, and key components._ diff --git a/README.md b/README.md new file mode 100644 index 0000000..14299ab --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +Welcome to [base](./docs/base.md) diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..ee845ee --- /dev/null +++ b/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-primer diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..f8a688b --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,7 @@ +version: "3.8" +services: + dev: + build: + context: ./docker + ports: + - "8080:80" diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..4f60076 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,28 @@ +# Use the latest Ubuntu LTS as a base image +FROM ubuntu:22.04 + +# Set non-interactive frontend for package installation +ENV DEBIAN_FRONTEND=noninteractive + +# Update package lists and install common development tools and NGINX +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + build-essential \ + git \ + curl \ + wget \ + nginx \ + && apt-get clean && \ + rm -rf /var/lib/apt/lists/* + +# Copy the NGINX configuration file +COPY nginx.conf /etc/nginx/nginx.conf + +# Copy the static HTML content +COPY html/ /var/www/html/ + +# Expose port 80 for the web server +EXPOSE 80 + +# Start NGINX when the container launches +CMD ["nginx", "-g", "daemon off;"] diff --git a/docker/html/index.html b/docker/html/index.html new file mode 100644 index 0000000..8e55469 --- /dev/null +++ b/docker/html/index.html @@ -0,0 +1 @@ +pong diff --git a/docker/nginx.conf b/docker/nginx.conf new file mode 100644 index 0000000..112361a --- /dev/null +++ b/docker/nginx.conf @@ -0,0 +1,37 @@ +user www-data; +worker_processes auto; +pid /run/nginx.pid; +include /etc/nginx/modules-enabled/*.conf; + +events { + worker_connections 768; +} + +http { + sendfile on; + tcp_nopush on; + tcp_nodelay on; + keepalive_timeout 65; + types_hash_max_size 2048; + + include /etc/nginx/mime.types; + default_type application/octet-stream; + + ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; # Dropping SSLv3, ref: POODLE + ssl_prefer_server_ciphers on; + + access_log /var/log/nginx/access.log; + error_log /var/log/nginx/error.log; + + gzip on; + + server { + listen 80; + server_name localhost; + + location / { + root /var/www/html; + index index.html index.htm; + } + } +} diff --git a/docs/base.md b/docs/base.md new file mode 100644 index 0000000..c8b2c43 --- /dev/null +++ b/docs/base.md @@ -0,0 +1,19 @@ +# The `base` Philosophy + +Welcome to `base`. This repository is designed to be a robust, professional, and well-documented starting point for new software 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. + +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. + +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. + +## 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. diff --git a/docs/docker.md b/docs/docker.md new file mode 100644 index 0000000..8a35ef0 --- /dev/null +++ b/docs/docker.md @@ -0,0 +1,52 @@ +# Docker-based Development Environment + +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`**: This is the blueprint for our development image. It starts from a standard Ubuntu 22.04 base, then installs NGINX and a set of common, language-agnostic development tools (`git`, `curl`, `build-essential`, etc.). +- **`docker/nginx.conf`**: This is a standard configuration file for the NGINX web server. It's set up to serve the content of the `docker/html` directory. +- **`docker/html/index.html`**: This simple file contains the word `pong` and is served by NGINX. It provides a simple way to check if the environment is running correctly (a "health check"). +- **`docker-compose.yml`**: This file makes it easy to build and run the development environment. It defines a single service named `dev` and maps port 80 inside the container to port 8080 on your local machine. +- **`.dockerignore`**: This file tells Docker which files and directories to exclude from the build context, which helps to speed up the image build process. + +## 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. + +1. **Build and Run the Container:** + 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. + +2. **Verify It's Running:** + 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: + + ```bash + 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. + +4. **Stopping the Environment:** + To stop the container, run: + ```bash + docker-compose down + ``` + +## Extending the Environment + +You can easily extend this environment by modifying the `docker/Dockerfile`. For example, to install Python, you could add the following line: + +```Dockerfile +RUN apt-get update && apt-get install -y python3 python3-pip +``` diff --git a/docs/github-codespaces.md b/docs/github-codespaces.md new file mode 100644 index 0000000..68abc2e --- /dev/null +++ b/docs/github-codespaces.md @@ -0,0 +1,20 @@ +# GitHub Codespaces + +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` file. This file instructs GitHub Codespaces to: + +1. **Use the Docker Environment:** It references our `docker-compose.yml` file to spin up the same development environment that you would use locally. +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 + +To get started with Codespaces: + +1. Click the **"Code"** button at the top of the repository page. +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. diff --git a/docs/github-pages.md b/docs/github-pages.md new file mode 100644 index 0000000..e2309f8 --- /dev/null +++ b/docs/github-pages.md @@ -0,0 +1,21 @@ +# GitHub Pages Site + +This repository is configured to use [GitHub Pages](https://pages.github.com/) to host a simple, clean website for the project. + +## How It Works + +The site is built and deployed by the `.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` file as the content for the homepage (`index.html`) of the site. +4. **Styling:** The `_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 + +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. diff --git a/docs/github-workflows.md b/docs/github-workflows.md new file mode 100644 index 0000000..5d97f72 --- /dev/null +++ b/docs/github-workflows.md @@ -0,0 +1,23 @@ +# GitHub Workflows Documentation + +This document explains the purpose and usage of the GitHub Actions workflows included in this repository. + +## `ci.yml` + +- **Purpose:** This workflow runs on every push and pull request to the `main` branch. It uses [Prettier](https://prettier.io/) to check for consistent formatting in Markdown and YAML files, ensuring code quality and readability. +- **Triggers:** `push`, `pull_request` to `main`. + +## `pages.yml` + +- **Purpose:** This workflow builds and deploys the project's documentation as a GitHub Pages website. It uses the root `README.md` as the homepage. +- **Triggers:** `push` to `main`, `workflow_dispatch`. + +## `release-on-tag.yml` + +- **Purpose:** This workflow automates the creation of GitHub Releases. +- **Triggers:** `push` of a new tag matching the pattern `v*.*.*`. +- **Usage:** + 1. Edit the `.github/RELEASE_TITLE.txt` and `.github/RELEASE_BODY.md` files to describe the release. You can use the `${TAG}` variable. + 2. Commit these changes. + 3. Push a new tag (e.g., `git tag v1.0.0 && git push origin v1.0.0`). + 4. The workflow will automatically create a new release with your notes, a full changelog, and a link to the diff. diff --git a/docs/licensing.md b/docs/licensing.md new file mode 100644 index 0000000..d59cf72 --- /dev/null +++ b/docs/licensing.md @@ -0,0 +1,30 @@ +# Licensing Information + +This repository is distributed under the MIT License, the full text of which is available in the `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. + +[Learn more about the MIT License](https://choosealicense.com/licenses/mit/). + +## How to Use the `LICENSE` File + +The included `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. + +For example: + +``` +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. + +### 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. diff --git a/docs/render.md b/docs/render.md new file mode 100644 index 0000000..89b95d8 --- /dev/null +++ b/docs/render.md @@ -0,0 +1,23 @@ +# Deploying to Render.com + +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: + +1. **Create a Web Service:** Define a service of type `web`. +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. + +## Getting Started + +To deploy this repository to your own Render account: + +1. Create a new "Blueprint" service in the Render dashboard. +2. Connect the GitHub repository you created from this template. +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. diff --git a/docs/standard-files.md b/docs/standard-files.md new file mode 100644 index 0000000..e4217a1 --- /dev/null +++ b/docs/standard-files.md @@ -0,0 +1,27 @@ +# Standard Repository Files + +This document explains the purpose of the standard, language-agnostic configuration files included in this repository. + +## `.gitignore` + +This file tells the `git` version control system which files and directories to ignore. The one included in this repository is pre-populated with common ignores for operating system files (like `.DS_Store` on macOS) and IDE configuration folders (like `.vscode`). + +[Learn more about `.gitignore`](https://git-scm.com/docs/gitignore). + +## `.editorconfig` + +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` + +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` + +This file configures the [Prettier](https://prettier.io/) code formatter. Prettier is used in the `ci.yml` workflow to ensure that all Markdown and YAML files in the repository have a consistent style. + +[Learn more about Prettier configuration](https://prettier.io/docs/en/configuration.html). diff --git a/docs/template-repo.md b/docs/template-repo.md new file mode 100644 index 0000000..2048a0c --- /dev/null +++ b/docs/template-repo.md @@ -0,0 +1,28 @@ +# 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). + +## GitHub Settings + +Ensure the following setting is enabled in the repository's main settings page (`Settings` > `General`): + +- [x] **Template repository** + +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` and `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/` are tested and functioning. +- [ ] All placeholder files are clear and provide good guidance. +- [ ] The `AGENTS.md` file has been updated to reflect any changes that would affect AI assistants. diff --git a/render.yaml b/render.yaml new file mode 100644 index 0000000..4dc466e --- /dev/null +++ b/render.yaml @@ -0,0 +1,6 @@ +services: + - type: web + name: base-template-app + env: docker + plan: free + healthCheckPath: /