From 363a6bf1608e05b2d1466543a06989881fb6814a Mon Sep 17 00:00:00 2001 From: saltines321-debug Date: Thu, 21 May 2026 10:01:49 -0700 Subject: [PATCH 1/3] Add reusable DevEx workflows and onboarding automation --- .github/workflows/ci.yml | 19 ++++++ .github/workflows/release.yml | 22 +++++++ .github/workflows/reusable-quality.yml | 84 ++++++++++++++++++++++++++ CONTRIBUTING.md | 9 ++- README.md | 13 +++- docs/developer-setup.md | 69 +++++++++++++++++++++ scripts/bootstrap.sh | 16 +++++ 7 files changed, 229 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release.yml create mode 100644 .github/workflows/reusable-quality.yml create mode 100644 docs/developer-setup.md create mode 100755 scripts/bootstrap.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..f4c18c0 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,19 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + quality: + uses: ./.github/workflows/reusable-quality.yml + with: + setup-node: false + run-format-check: false + run-lint: false + run-test: false diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..4059050 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,22 @@ +name: Release + +on: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: write + pull-requests: write + +jobs: + release-please: + runs-on: ubuntu-latest + + steps: + - name: Release Please + uses: googleapis/release-please-action@v4 + with: + release-type: simple + changelog-types: '[{"type":"feat","section":"Features","hidden":false},{"type":"fix","section":"Bug Fixes","hidden":false},{"type":"chore","section":"Maintenance","hidden":false}]' diff --git a/.github/workflows/reusable-quality.yml b/.github/workflows/reusable-quality.yml new file mode 100644 index 0000000..8566a01 --- /dev/null +++ b/.github/workflows/reusable-quality.yml @@ -0,0 +1,84 @@ +name: Reusable Quality Checks + +on: + workflow_call: + inputs: + checkout-fetch-depth: + description: Git checkout fetch depth. + required: false + default: 0 + type: number + setup-node: + description: Enable Node.js setup. + required: false + default: true + type: boolean + node-version: + description: Node.js version for JS/TS projects. + required: false + default: '20' + type: string + run-format-check: + description: Run formatting validation command. + required: false + default: true + type: boolean + format-command: + description: Command used for format validation. + required: false + default: npm run format:check --if-present + type: string + run-lint: + description: Run lint command. + required: false + default: true + type: boolean + lint-command: + description: Command used for lint validation. + required: false + default: npm run lint --if-present + type: string + run-test: + description: Run automated tests. + required: false + default: true + type: boolean + test-command: + description: Command used to run test suite. + required: false + default: npm test --if-present + type: string + +jobs: + quality: + name: Quality + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: ${{ inputs.checkout-fetch-depth }} + + - name: Set up Node.js + if: ${{ inputs.setup-node }} + uses: actions/setup-node@v4 + with: + node-version: ${{ inputs.node-version }} + cache: npm + + - name: Install dependencies + if: ${{ inputs.setup-node }} + run: npm ci + + - name: Format check + if: ${{ inputs.run-format-check }} + run: ${{ inputs.format-command }} + + - name: Lint + if: ${{ inputs.run-lint }} + run: ${{ inputs.lint-command }} + + - name: Test + if: ${{ inputs.run-test }} + run: ${{ inputs.test-command }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0cf9ae4..3bc662d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ Thanks for your interest in contributing. 1. Fork and create a branch: `feature/short-description` 2. Make your changes with clear commit messages. -3. Run tests/lint locally (if configured). +3. Run local validation (`format:check`, `lint`, `test`) before opening your PR. 4. Open a pull request using the PR template. ## Pull request checklist @@ -22,3 +22,10 @@ Thanks for your interest in contributing. - [ ] Docs are updated (if behavior changed) - [ ] Changelog updated (if needed) + + +## Local automation defaults + +- Bootstrap: `./scripts/bootstrap.sh` +- Setup guide: `docs/developer-setup.md` +- CI workflows: `.github/workflows/` diff --git a/README.md b/README.md index 093ec3f..ffb9acd 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,9 @@ A general-purpose GitHub repository template you can copy to bootstrap new proje ## Suggested next steps -- Add CI workflows in `.github/workflows/` for linting/tests. +- Review prebuilt GitHub Actions workflows in `.github/workflows/` and enable commands for your stack. - Add project-specific architecture docs in `docs/`. -- Add release automation if you publish packages. +- Configure `release.yml` for semantic release PRs/tags if you publish artifacts. ## Repository layout @@ -38,3 +38,12 @@ LICENSE SECURITY.md ``` + + +## Automation included + +- Reusable quality workflow: `.github/workflows/reusable-quality.yml` +- CI entry workflow: `.github/workflows/ci.yml` +- Release automation workflow: `.github/workflows/release.yml` +- Bootstrap script: `scripts/bootstrap.sh` +- Developer setup guide: `docs/developer-setup.md` diff --git a/docs/developer-setup.md b/docs/developer-setup.md new file mode 100644 index 0000000..2f866c0 --- /dev/null +++ b/docs/developer-setup.md @@ -0,0 +1,69 @@ +# Developer Setup + +This guide provides generic onboarding defaults intended for template-based repositories. + +## 1) Prerequisites + +- Git 2.40+ +- A language runtime/toolchain for your project (Node, Python, Go, etc.) +- A package manager (`npm`, `pnpm`, `pip`, `poetry`, `go`, etc.) + +## 2) Bootstrap locally + +```bash +git clone +cd +./scripts/bootstrap.sh +``` + +If your repository is not Node.js based, adapt `scripts/bootstrap.sh` to your stack and keep command names consistent with CI. + +## 3) Recommended task contract + +To keep automation portable, define task commands with predictable names: + +- `format:check` — formatting validation +- `lint` — static analysis/linting +- `test` — automated tests + +This template's reusable workflow can call any shell command, but these names improve discoverability. + +## 4) CI customization + +The repository ships with: + +- `.github/workflows/reusable-quality.yml` (reusable workflow) +- `.github/workflows/ci.yml` (default entry workflow) +- `.github/workflows/release.yml` (semantic release PR/tag automation) + +In `ci.yml`, enable checks by setting: + +- `setup-node: true` for JS/TS projects +- `run-format-check: true` +- `run-lint: true` +- `run-test: true` + +Then optionally override commands: + +```yaml +with: + setup-node: true + format-command: npm run format:check + lint-command: npm run lint + test-command: npm test +``` + +## 5) Branch and PR workflow + +1. Create a branch from `main`. +2. Run local validation commands before opening a PR. +3. Open a focused PR and include context for reviewers. +4. Merge only when CI checks pass. + +## 6) Lightweight automation standards + +- Keep workflows minimal and composable. +- Prefer reusable workflows (`workflow_call`) over duplicated YAML. +- Avoid stack-specific assumptions in template defaults. +- Keep commands configurable through workflow inputs. +- Fail fast in CI and keep logs clear. diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh new file mode 100755 index 0000000..8c26d3b --- /dev/null +++ b/scripts/bootstrap.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [[ ! -f package.json ]]; then + echo "No package.json found. This bootstrap script is currently oriented to Node.js projects." + echo "Copy and adapt scripts/bootstrap.sh for your stack (Python, Go, Rust, etc.)." + exit 0 +fi + +if command -v npm >/dev/null 2>&1; then + npm ci + echo "Dependencies installed." +else + echo "npm is not installed. Please install Node.js 20+ and retry." + exit 1 +fi From dd1d1db1c23672088a692b7e925fd9fd99aa8532 Mon Sep 17 00:00:00 2001 From: saltines321-debug Date: Thu, 21 May 2026 10:07:07 -0700 Subject: [PATCH 2/3] Resolve README merge conflicts with main --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 57 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index ffb9acd..901c4cf 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,71 @@ -# Repository Template +# OSS Repository Template -A general-purpose GitHub repository template you can copy to bootstrap new projects quickly. +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](CONTRIBUTING.md) +[![Security Policy](https://img.shields.io/badge/security-policy-blue.svg)](SECURITY.md) -## What this template includes +A reusable, professional baseline for open source repositories. -- Clear project overview and quick-start sections -- Community health files (`CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md`) -- GitHub issue templates (bug report, feature request) -- Pull request template -- Starter changelog and keep-it-clean `.gitignore` +This template is intentionally generic so it can be adopted across teams, products, and languages with minimal changes. -## Getting started +## Why use this template + +- **Consistent OSS standards**: ship repository health files from day one. +- **Faster onboarding**: contributors and maintainers get clear guidance. +- **Scalable governance**: reusable conventions for labels, milestones, and releases. +- **Production-grade defaults**: practical configuration for common Git and editor workflows. + +## Included components + +- Repository health files: + - `LICENSE` + - `CONTRIBUTING.md` + - `SECURITY.md` + - `CODE_OF_CONDUCT.md` +- GitHub collaboration scaffolding: + - Issue templates + - Pull request template + - `CODEOWNERS` +- Standards and governance documentation: + - `docs/REPOSITORY_STANDARDS.md` +- Baseline repository config: + - `.editorconfig` + - `.gitattributes` + - `.gitignore` + +## Quick start 1. Click **Use this template** on GitHub. -2. Rename the repository and adjust this README to your project. -3. Choose and verify your license terms in `LICENSE`. -4. Update contact points in `SECURITY.md` and `CODEOWNERS`. +2. Rename the repository and update project-specific fields. +3. Confirm or replace `LICENSE` for your legal requirements. +4. Update contacts in `SECURITY.md`, `CODEOWNERS`, and template placeholders. 5. Enable branch protection and required status checks. +## Recommended repository settings + +- Protect the default branch (`main`/`master`). +- Require pull requests and at least one approving review. +- Require status checks before merge. +- Enable secret scanning and dependency alerts. +- Restrict force pushes and branch deletion. + +## Versioning and releases + +Use [Semantic Versioning](https://semver.org/) and keep a human-readable `CHANGELOG.md`. + +- **MAJOR**: incompatible API or behavior changes. +- **MINOR**: backward-compatible functionality. +- **PATCH**: backward-compatible fixes. + +## Naming conventions + +See `docs/REPOSITORY_STANDARDS.md` for reusable naming and governance conventions. + ## Suggested next steps - Review prebuilt GitHub Actions workflows in `.github/workflows/` and enable commands for your stack. -- Add project-specific architecture docs in `docs/`. +- Add language/tool-specific linting and formatting. +- Add architecture and operations documentation in `docs/`. - Configure `release.yml` for semantic release PRs/tags if you publish artifacts. ## Repository layout @@ -38,8 +82,6 @@ LICENSE SECURITY.md ``` - - ## Automation included - Reusable quality workflow: `.github/workflows/reusable-quality.yml` From 722865fa1a2bf1de010f0c6a084a20d783cd9855 Mon Sep 17 00:00:00 2001 From: saltines321-debug Date: Thu, 21 May 2026 10:12:41 -0700 Subject: [PATCH 3/3] Resolve contributing guide conflict --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3bc662d..b80fa25 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,8 +22,6 @@ Thanks for your interest in contributing. - [ ] Docs are updated (if behavior changed) - [ ] Changelog updated (if needed) - - ## Local automation defaults - Bootstrap: `./scripts/bootstrap.sh`