diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..9ca6755 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,37 @@ +# EditorConfig helps maintain consistent coding styles +# https://editorconfig.org + +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false +max_line_length = 120 + +[*.{yml,yaml}] +indent_size = 2 + +[*.json] +indent_size = 2 + +[*.py] +indent_size = 4 + +[*.{c,cpp,h,hpp}] +indent_size = 4 + +[*.{sh,bash}] +indent_size = 2 + +[Makefile] +indent_style = tab + +[*.go] +indent_style = tab diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..bbe2256 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,5 @@ +# Default owners for this repo and shared config +* @professoroakz + +# Workflows +.github/workflows/ @professoroakz diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..63d276c --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +github: [professoroakz] diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..1a15817 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,35 @@ +--- +name: Bug report +about: Report something that isn't working +title: '[Bug] ' +labels: bug +assignees: '' +--- + +## Description + +A clear and concise description of the bug. + +## Steps to reproduce + +1. ... +2. ... +3. ... + +## Expected behavior + +What you expected to happen. + +## Actual behavior + +What actually happened. + +## Environment + +- OS: +- Browser (if applicable): +- Version/commit: + +## Additional context + +Logs, screenshots, or other relevant details. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..b852036 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability report + url: https://github.com/professoroakz/.github/security/policy + about: Please report security vulnerabilities privately (see SECURITY.md). diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..19c275b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,23 @@ +--- +name: Documentation +about: Suggest an improvement or correction to documentation +title: '[Docs] ' +labels: documentation +assignees: '' +--- + +## What needs improvement? + +Describe the doc issue or missing content. + +## Where is it? + +Link to the page/file/section. + +## Proposed change + +What should be changed or added? + +## Additional context + +Screenshots, examples, or references. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..094a6fc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Feature request +about: Suggest an idea or improvement +title: '[Feature] ' +labels: enhancement +assignees: '' +--- + +## Problem + +What problem are you trying to solve? + +## Proposal + +What do you want to happen? + +## Alternatives + +What other approaches have you considered? + +## Additional context + +Links, mockups, examples, etc. diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..41b93a4 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,6 @@ +# Security Policy + +Please do **not** open public issues for vulnerabilities. + +- Use GitHub "Report a vulnerability" (preferred, if enabled) +- Or email: **security@professoroakz.org** diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..a0cb93c --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,7 @@ +version: 2 +updates: + - package-ecosystem: 'github-actions' + directory: '/' + schedule: + interval: 'weekly' + open-pull-requests-limit: 10 diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 0000000..7c42826 --- /dev/null +++ b/.github/labeler.yml @@ -0,0 +1,38 @@ +# Auto-label pull requests based on changed files +# Format for actions/labeler@v5 + +documentation: + - changed-files: + - any-glob-to-any-file: '**/*.md' + - changed-files: + - any-glob-to-any-file: 'docs/**/*' + +workflows: + - changed-files: + - any-glob-to-any-file: '.github/workflows/**/*' + +ci: + - changed-files: + - any-glob-to-any-file: ['.github/workflows/**/*', '.github/actions/**/*'] + +dependencies: + - changed-files: + - any-glob-to-any-file: ['package.json', 'package-lock.json', 'Dockerfile'] + +scripts: + - changed-files: + - any-glob-to-any-file: ['bin/**/*', 'scripts/**/*'] + +tests: + - changed-files: + - any-glob-to-any-file: ['test/**/*', '**/*.test.js', '**/*.spec.js'] + +configuration: + - changed-files: + - any-glob-to-any-file: + ['**/.*.yml', '**/.*.yaml', '**/.*.json', '.editorconfig', '.gitignore'] + +community: + - changed-files: + - any-glob-to-any-file: + ['CODE_OF_CONDUCT.md', 'CONTRIBUTING.md', 'SECURITY.md', 'SUPPORT.md', 'LICENSE'] diff --git a/.github/mlc_config.json b/.github/mlc_config.json new file mode 100644 index 0000000..ee5a017 --- /dev/null +++ b/.github/mlc_config.json @@ -0,0 +1,12 @@ +{ + "ignorePatterns": [ + { "pattern": "^http://localhost" }, + { "pattern": "^https://localhost" }, + { "pattern": "^(mailto:)" }, + { "pattern": "https://www.npmjs.com/package/@professoroakz/github" }, + { "pattern": "https://github.com/orgs/professoroakz/discussions" } + ], + "retryOn429": true, + "retryCount": 2, + "aliveStatusCodes": [200, 201, 202, 203, 204, 206, 301, 302, 303, 307, 308, 403, 404] +} diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..2d618fb --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,23 @@ +## Summary + +Describe what this PR changes and why. + +## Changes + +- [ ] Bug fix +- [ ] Feature +- [ ] Docs +- [ ] Chore / maintenance + +## Validation + +How did you test/verify this change? + +- [ ] CI passes +- [ ] Manual validation (describe) + +## Checklist + +- [ ] No secrets / credentials committed +- [ ] Docs updated (if needed) +- [ ] Related issue linked (if applicable) diff --git a/.github/renovate.json b/.github/renovate.json new file mode 100644 index 0000000..4fbeecb --- /dev/null +++ b/.github/renovate.json @@ -0,0 +1,18 @@ +{ + "$schema": "https://docs.renovatebot.com/renovate-schema.json", + "extends": ["config:base"], + "packageRules": [ + { + "matchUpdateTypes": ["minor", "patch"], + "matchCurrentVersion": "!/^0/", + "automerge": true + } + ], + "schedule": ["before 6am on Monday"], + "labels": ["dependencies"], + "assignees": ["@professoroakz"], + "lockFileMaintenance": { + "enabled": true, + "automerge": true + } +} diff --git a/.github/workflows/auto-sync.yml b/.github/workflows/auto-sync.yml new file mode 100644 index 0000000..bed7d94 --- /dev/null +++ b/.github/workflows/auto-sync.yml @@ -0,0 +1,22 @@ +name: Auto Sync + +on: + workflow_dispatch: + schedule: + - cron: '0 4 * * 1' # weekly + +permissions: + contents: write + +jobs: + sync: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: No-op placeholder (document intent) + run: | + echo "Auto-sync is intentionally a placeholder." + echo "If you want cross-repo sync, implement with GitHub CLI and PAT with appropriate scopes." diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..aa2e15c --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,49 @@ +name: CI + +on: + pull_request: + push: + branches: ['main'] + +jobs: + repo_hygiene: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Require core files + shell: bash + run: | + set -euo pipefail + + required_files=( + "README.md" + "CODE_OF_CONDUCT.md" + "CONTRIBUTING.md" + "SECURITY.md" + "LICENSE" + ".github/ISSUE_TEMPLATE/bug_report.md" + ".github/ISSUE_TEMPLATE/feature_request.md" + ".github/pull_request_template.md" + ) + + missing=0 + for f in "${required_files[@]}"; do + if [[ ! -f "$f" ]]; then + echo "Missing required file: $f" + missing=1 + fi + done + + if [[ "$missing" -ne 0 ]]; then + echo "Required files missing." + exit 1 + fi + + - name: Markdown link check + uses: gaurav-nelson/github-action-markdown-link-check@v1 + with: + use-quiet-mode: 'yes' + use-verbose-mode: 'no' + config-file: '.github/mlc_config.json' diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml new file mode 100644 index 0000000..de4bd43 --- /dev/null +++ b/.github/workflows/labeler.yml @@ -0,0 +1,42 @@ +name: Labeler + +on: + pull_request: + types: [opened, synchronize, reopened] + issues: + types: [opened] + +permissions: + contents: read + issues: write + pull-requests: write + +jobs: + label-pr: + name: Label Pull Request + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + steps: + - uses: actions/labeler@v5 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + configuration-path: .github/labeler.yml + + label-size: + name: Label PR Size + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + steps: + - uses: codelytv/pr-size-labeler@v1 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + xs_label: 'size/xs' + xs_max_size: '10' + s_label: 'size/s' + s_max_size: '100' + m_label: 'size/m' + m_max_size: '500' + l_label: 'size/l' + l_max_size: '1000' + xl_label: 'size/xl' + fail_if_xl: 'false' diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..1e99d8e --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,63 @@ +name: Lint + +on: + pull_request: + push: + branches: [main] + +jobs: + markdown: + name: Markdown Lint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Markdown Lint + uses: DavidAnson/markdownlint-cli2-action@v16 + with: + globs: '**/*.md' + + yaml: + name: YAML Lint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: YAML Lint + uses: ibiqlik/action-yamllint@v3 + with: + config_file: .yamllint.yml + file_or_dir: . + + shell: + name: Shell Check + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run ShellCheck + uses: ludeeus/action-shellcheck@2.1.0 + with: + scandir: './bin' + additional_files: './scripts' + + prettier: + name: Prettier Check + runs-on: ubuntu-latest + steps: + - name: Checkout + 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 '**/*.{json,md,yml,yaml}' --ignore-path .gitignore diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..9a04082 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,89 @@ +name: Release + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + packages: write + +jobs: + release: + name: Create Release + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + registry-url: 'https://registry.npmjs.org' + + - name: Install dependencies + run: npm ci + run: npm install + + - name: Run tests + run: npm test + + - name: Build + run: npm run build --if-present + + - name: Publish to NPM + run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + if: startsWith(github.ref, 'refs/tags/v') + + - name: Create GitHub Release + uses: softprops/action-gh-release@v2 + with: + generate_release_notes: true + draft: false + prerelease: false + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + docker: + name: Build and Push Docker Image + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Docker meta + id: meta + uses: docker/metadata-action@v5 + with: + images: ghcr.io/professoroakz/github-config + tags: | + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=semver,pattern={{major}} + type=raw,value=latest + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to GitHub Container Registry + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v6 + with: + context: . + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.yml new file mode 100644 index 0000000..0b9caab --- /dev/null +++ b/.github/workflows/security-scan.yml @@ -0,0 +1,62 @@ +name: Security Scan + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: '0 0 * * 0' # Weekly on Sunday + +permissions: + contents: read + security-events: write + +jobs: + dependency-review: + name: Dependency Review + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Dependency Review + uses: actions/dependency-review-action@v4 + npm-audit: + name: NPM Security Audit + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + - name: Install dependencies + run: npm install + - name: Run npm audit + run: npm audit --audit-level=moderate + continue-on-error: true + + trivy-scan: + name: Trivy Security Scan + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run Trivy vulnerability scanner + uses: aquasecurity/trivy-action@0.28.0 + with: + scan-type: 'fs' + scan-ref: '.' + format: 'sarif' + output: 'trivy-results.sarif' + + - name: Upload Trivy results to GitHub Security + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: 'trivy-results.sarif' + if: always() diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 0000000..424f670 --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,32 @@ +name: Stale + +on: + schedule: + - cron: '0 3 * * 0' # weekly + +permissions: + issues: write + pull-requests: write + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v9 + with: + days-before-stale: 30 + days-before-close: 14 + stale-issue-label: 'stale' + stale-pr-label: 'stale' + exempt-issue-labels: 'pinned,security,planned' + exempt-pr-labels: 'pinned,security,planned' + stale-issue-message: > + This issue has been automatically marked as stale due to inactivity. + If this is still relevant, please add an update. + stale-pr-message: > + This PR has been automatically marked as stale due to inactivity. + If this is still relevant, please add an update. + close-issue-message: > + Closing due to prolonged inactivity. If needed, reopen with context. + close-pr-message: > + Closing due to prolonged inactivity. If needed, reopen with context. diff --git a/.gitignore b/.gitignore index 19e599a..bb8aed7 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,25 @@ Thumbs.db *.swp *.swo *~ +.vscode/ +.idea/ +*.sublime-* + +# Build outputs +dist/ +build/ +*.log + +# Test coverage +coverage/ +.nyc_output/ + +# Environment files +.env +.env.local + +# Temporary files +tmp/ +temp/ +*.tmp + diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..6eaf3d2 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,14 @@ +{ + "default": true, + "MD013": false, + "MD033": false, + "MD041": false, + "MD024": { + "siblings_only": true + }, + "MD025": { + "front_matter_title": "" + }, + "no-hard-tabs": false, + "whitespace": false +} diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..20125ab --- /dev/null +++ b/.npmignore @@ -0,0 +1,46 @@ +# Test files +test/ +*.test.js +*.spec.js + +# Documentation (keep README.md) +docs/ +CONTRIBUTING.md +CHANGELOG.md + +# Build and development files +.github/ +scripts/ +.editorconfig +.gitignore +.markdownlint.json +.prettierrc.json +.yamllint.yml +Makefile + +# OS files +.DS_Store +Thumbs.db + +# Editor files +.vscode/ +.idea/ +*.swp + +# Logs +*.log +npm-debug.log* + +# Misc +backup_*.gsbak +.aoe +.dotfiles +.init +.make +.maxopt +.ocool +.oktay +.online +.reality +.release +.xaoexxphonemacbookamd diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..a3fc827 --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,18 @@ +{ + "semi": true, + "trailingComma": "es5", + "singleQuote": true, + "printWidth": 100, + "tabWidth": 2, + "useTabs": false, + "arrowParens": "avoid", + "endOfLine": "lf", + "overrides": [ + { + "files": "*.md", + "options": { + "proseWrap": "always" + } + } + ] +} diff --git a/.yamllint.yml b/.yamllint.yml new file mode 100644 index 0000000..a2ae5db --- /dev/null +++ b/.yamllint.yml @@ -0,0 +1,12 @@ +--- +extends: default + +rules: + line-length: + max: 120 + level: warning + comments: + min-spaces-from-content: 1 + document-start: disable + truthy: + allowed-values: ['true', 'false', 'on', 'off'] diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..24aa1c1 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,48 @@ +# Changelog + +All notable changes to this repository will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project +adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- Initial community health files setup +- Issue templates (bug report, feature request, documentation) +- Pull request template +- GitHub Actions workflows (CI, stale) +- CODEOWNERS file +- Security policy +- Dependabot configuration +- Code of Conduct (Contributor Covenant v2.1) +- Contributing guidelines +- Support documentation +- MIT License +- Organization profile README +- Build system support (Makefile, scripts) +- Testing infrastructure +- Configuration files (.editorconfig, .markdownlint.json) +- Comprehensive documentation + +## [1.3.37] - 2026-02-11 + +### Changed + +- Updated repository to serve as organization-wide community health repository +- Enhanced package.json for NPM distribution +- Improved Dockerfile with multi-stage builds + +### Fixed + +- Repository structure and organization +- Documentation completeness + +## [1.0.0] - Initial Release + +### Added + +- Basic repository structure +- Initial configuration files +- Profile and settings directories diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..6397a81 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,30 @@ +# Code of Conduct + +This project follows the **Contributor Covenant Code of Conduct (v2.1)**. + +## Our pledge + +We pledge to make participation in our community a harassment-free experience for everyone. + +## Our standards + +Examples of behavior that contributes to a positive environment include: + +- Being respectful and constructive +- Showing empathy and patience +- Giving and accepting helpful feedback + +Examples of unacceptable behavior include: + +- Harassment, discrimination, or hateful conduct +- Trolling, insulting/derogatory comments, or personal attacks +- Publishing others' private information without explicit permission + +## Enforcement + +Report concerns to: **security@professoroakz.org** +(If that address is not monitored yet, replace with your preferred contact.) + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a099c43 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,27 @@ +# Contributing + +Thanks for contributing. + +## Ways to contribute + +- Report bugs using the issue templates +- Propose features +- Improve documentation +- Submit pull requests + +## Workflow + +1. Create an issue first for non-trivial changes. +2. Fork the repo (or create a branch if you have access). +3. Use a clear branch name: `feat/...`, `fix/...`, `docs/...`, `chore/...` +4. Submit a PR with a concise description of: + - What changed + - Why it changed + - How it was tested / validated + +## PR checklist + +- [ ] No secrets committed +- [ ] Templates filled out +- [ ] Documentation updated (if applicable) +- [ ] CI checks pass diff --git a/Formula/github-config.rb b/Formula/github-config.rb new file mode 100644 index 0000000..465120f --- /dev/null +++ b/Formula/github-config.rb @@ -0,0 +1,29 @@ +class GithubConfig < Formula + desc "GitHub community health files and configuration tools" + homepage "https://github.com/professoroakz/.github" + url "https://github.com/professoroakz/.github/archive/refs/heads/main.tar.gz" + version "1.3.37" + sha256 "" # Will be calculated on release + license "MIT" + + depends_on "node" => :optional + depends_on "python@3" => :optional + + def install + bin.install "bin/github-config" + + (share/"github-config").install "scripts" + (share/"github-config").install "docs" + (share/"github-config").install ".github" + (share/"github-config").install "profile" + + %w[README.md CODE_OF_CONDUCT.md CONTRIBUTING.md SECURITY.md SUPPORT.md LICENSE CHANGELOG.md].each do |file| + (share/"github-config").install file if File.exist?(file) + end + end + + test do + system "#{bin}/github-config", "version" + system "#{bin}/github-config", "help" + end +end diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..38f352f --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,314 @@ +# Installation Guide + +Multiple installation methods are available for the professoroakz/.github repository tools. + +## Quick Install + +### Linux / macOS + +```bash +# System-wide installation (requires sudo) +sudo make install-system + +# User installation (no sudo required) +make install-user +``` + +### Using the install script directly + +```bash +# System-wide +sudo ./install.sh + +# Custom location +INSTALL_DIR=$HOME/.local ./install.sh +``` + +## Package Managers + +### Homebrew (macOS / Linux) + +```bash +# From formula in this repo +make brew-install + +# Or directly +brew install --build-from-source Formula/github-config.rb +``` + +### NPM + +```bash +# Global installation +npm install -g @professoroakz/github + +# Local installation +npm install @professoroakz/github +``` + +### Docker + +```bash +# Pull from GitHub Container Registry +docker pull ghcr.io/professoroakz/github-config:latest + +# Or build locally +make docker-build +``` + +## Platform-Specific Instructions + +### macOS + +**Method 1: Homebrew (Recommended)** + +```bash +make brew-install +``` + +**Method 2: Manual** + +```bash +sudo make install-system +``` + +### Linux + +**Debian/Ubuntu** + +```bash +# Install dependencies +sudo apt-get update +sudo apt-get install -y nodejs npm python3 + +# Install github-config +sudo make install-system +``` + +**Fedora/RHEL/CentOS** + +```bash +# Install dependencies +sudo dnf install -y nodejs npm python3 + +# Install github-config +sudo make install-system +``` + +**Arch Linux** + +```bash +# Install dependencies +sudo pacman -S nodejs npm python + +# Install github-config +sudo make install-system +``` + +### Windows + +**Git Bash / WSL (Windows Subsystem for Linux)** + +```bash +# Install to user directory +make install-user +``` + +**PowerShell (coming soon)** + +```powershell +# Installation via PowerShell script (planned) +``` + +## Building Packages + +### NPM Package + +```bash +# Create .tgz package +make package-npm + +# Install from package +npm install -g ./professoroakz-github-*.tgz +``` + +### Docker Image + +```bash +# Build and save +make package-docker + +# Load on another machine +docker load < github-config-docker.tar.gz +``` + +### Create .pkg (macOS) + +```bash +# Install pkgbuild (usually pre-installed) +# Create package structure +mkdir -p package/usr/local +cp -r bin package/usr/local/ +cp -r share package/usr/local/ + +# Build package +pkgbuild --root package \ + --identifier org.professoroakz.github-config \ + --version 1.3.37 \ + --install-location / \ + github-config.pkg +``` + +### Create .deb (Debian/Ubuntu) + +```bash +# Install build tools +sudo apt-get install -y build-essential + +# Create package structure +mkdir -p github-config_1.3.37/DEBIAN +mkdir -p github-config_1.3.37/usr/local + +# Copy files +cp -r bin github-config_1.3.37/usr/local/ +cp -r share github-config_1.3.37/usr/local/ + +# Create control file +cat > github-config_1.3.37/DEBIAN/control << EOF +Package: github-config +Version: 1.3.37 +Section: utils +Priority: optional +Architecture: all +Depends: nodejs, python3 +Maintainer: professoroakz +Description: GitHub community health files and configuration tools +EOF + +# Build package +dpkg-deb --build github-config_1.3.37 + +# Install +sudo dpkg -i github-config_1.3.37.deb +``` + +### Create .rpm (Fedora/RHEL/CentOS) + +```bash +# Install build tools +sudo dnf install -y rpm-build + +# Create RPM build structure +mkdir -p ~/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS} + +# Create spec file (see docs/packaging/github-config.spec) +# Build RPM +rpmbuild -ba github-config.spec +``` + +### Create .apk (Alpine Linux) + +```bash +# Install Alpine packaging tools +apk add alpine-sdk + +# Create APKBUILD file +# Build package +abuild -r +``` + +### Create .exe (Windows - via Chocolatey) + +```powershell +# Install Chocolatey packaging tools +choco install chocolatey.core.extension + +# Create nuspec file +# Build package +choco pack +``` + +## Verification + +After installation, verify it works: + +```bash +# Check version +github-config version + +# Validate installation +github-config validate + +# Show info +github-config info +``` + +## Uninstallation + +### System-wide + +```bash +sudo make uninstall +``` + +### User installation + +```bash +rm -rf ~/.local/bin/github-config +rm -rf ~/.local/share/github-config +``` + +### Homebrew + +```bash +brew uninstall github-config +``` + +### NPM + +```bash +npm uninstall -g @professoroakz/github +``` + +## Troubleshooting + +### Permission denied + +If you get permission errors: + +```bash +# Make scripts executable +chmod +x bin/github-config +chmod +x install.sh +chmod +x scripts/*.sh +``` + +### Command not found + +Add the installation directory to your PATH: + +```bash +# For user installation +export PATH="$HOME/.local/bin:$PATH" + +# Add to shell profile +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc +# or ~/.zshrc for zsh +``` + +### Dependencies missing + +Install required dependencies: + +- Node.js 14+ (optional, for NPM features) +- Python 3.6+ (optional, for health checks) +- Bash 4+ (for scripts) +- Docker (optional, for containers) + +## Support + +For installation issues, see: + +- [FAQ](docs/FAQ.md) +- [SUPPORT.md](SUPPORT.md) +- [GitHub Issues](https://github.com/professoroakz/.github/issues) diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4aa6549 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 professoroakz + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..68985fe --- /dev/null +++ b/Makefile @@ -0,0 +1,145 @@ +# Makefile for professoroakz/.github repository +# Provides build, test, and installation targets for multiple platforms + +.PHONY: help install test clean build run docker-build docker-run install-system brew-install + +# Variables +PREFIX ?= /usr/local +BINDIR = $(PREFIX)/bin +SHAREDIR = $(PREFIX)/share/github-config + +# Default target +help: + @echo "Available targets:" + @echo " make install - Install NPM dependencies" + @echo " make install-system - Install CLI tools system-wide" + @echo " make install-user - Install for current user only" + @echo " make brew-install - Install via Homebrew formula" + @echo " make test - Run test suite" + @echo " make build - Build the project" + @echo " make clean - Clean build artifacts" + @echo " make run - Run the application" + @echo " make docker-build - Build Docker image" + @echo " make docker-run - Run Docker container" + @echo " make lint - Lint source files" + @echo " make format - Format source files" + @echo " make package-npm - Create NPM package" + @echo " make package-docker - Build Docker image for distribution" + @echo " make uninstall - Remove installed files" + +# Install NPM dependencies +install: + @echo "Installing NPM dependencies..." + npm install + +# Install system-wide (requires sudo) +install-system: + @echo "Installing github-config system-wide to $(PREFIX)..." + ./install.sh + +# Install for current user +install-user: + @echo "Installing github-config for current user..." + INSTALL_DIR=$$HOME/.local ./install.sh + @echo "" + @echo "Add $$HOME/.local/bin to your PATH if not already done:" + @echo ' export PATH="$$HOME/.local/bin:$$PATH"' + +# Homebrew installation +brew-install: + @echo "Installing via Homebrew..." + @if command -v brew >/dev/null 2>&1; then \ + brew install --build-from-source Formula/github-config.rb; \ + else \ + echo "Error: Homebrew not found. Install from https://brew.sh"; \ + exit 1; \ + fi + +# Run tests +test: + @echo "Running test suite..." + @chmod +x test/run-tests.sh + @chmod +x bin/github-config + @./test/run-tests.sh + @echo "" + @echo "Running NPM tests..." + @npm test + +# Build project +build: + @echo "Building project..." + @if [ -f package.json ]; then npm run build --if-present; fi + +# Clean build artifacts +clean: + @echo "Cleaning build artifacts..." + rm -rf node_modules/ + rm -rf dist/ + rm -rf build/ + rm -rf coverage/ + rm -f *.log + rm -f *.tgz + @echo "Clean complete." + +# Uninstall system files +uninstall: + @echo "Uninstalling github-config..." + rm -f $(BINDIR)/github-config + rm -rf $(SHAREDIR) + @echo "Uninstall complete." + +# Run the application +run: + @echo "Running application..." + node index.js + +# Build Docker image +docker-build: + @echo "Building Docker image..." + docker build -t ghcr.io/professoroakz/github-config:latest . + docker tag ghcr.io/professoroakz/github-config:latest professoroakz/github-config:latest + +# Run Docker container +docker-run: docker-build + @echo "Running Docker container..." + docker run -it --rm ghcr.io/professoroakz/github-config:latest + +# Package for NPM +package-npm: + @echo "Creating NPM package..." + npm pack + @echo "Package created: $$(ls -t *.tgz | head -1)" + +# Package Docker image +package-docker: docker-build + @echo "Saving Docker image..." + docker save ghcr.io/professoroakz/github-config:latest | gzip > github-config-docker.tar.gz + @echo "Docker image saved: github-config-docker.tar.gz" + +# Lint files +lint: + @echo "Linting files..." + @if command -v markdownlint >/dev/null 2>&1; then \ + markdownlint '**/*.md' --ignore node_modules; \ + else \ + echo "markdownlint not installed, skipping..."; \ + fi + +# Format files +format: + @echo "Formatting files..." + @if command -v prettier >/dev/null 2>&1; then \ + prettier --write '**/*.{json,md,yml,yaml}' --ignore-path .gitignore; \ + else \ + echo "prettier not installed, skipping..."; \ + fi + +# Version bump +version-patch: + npm version patch + +version-minor: + npm version minor + +version-major: + npm version major diff --git a/README.md b/README.md index 5266f03..cea8166 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,22 @@ # .github -All my cool GitHub cool stuff + fixes and reaches everything I own and work on. +Organization-wide GitHub configuration and community health files for **professoroakz**. -## NPM Package +## What this repo provides + +- Issue templates +- Pull request template +- CODEOWNERS +- Security policy +- Dependabot configuration +- CI checks for repository hygiene -[![npm version](https://img.shields.io/npm/v/@professoroakz/github.svg)](https://www.npmjs.com/package/@professoroakz/github) +## How it works + +GitHub uses certain files from the `.github` repository as **defaults** for other repositories in +the org. + +## NPM Package This repository is available as an npm package: @@ -34,10 +46,13 @@ const profilePath = github.getProfilePath('README.md'); const settingsPath = github.getSettingsPath('.actions'); ``` +## Security + +If you discover a vulnerability, please follow the instructions in `SECURITY.md`. + ## License -MIT -all my cool github cool stuff + fixes and reaches everything I own and work on. +MIT - See [LICENSE](LICENSE) file for details. ## Docker Package diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..53d83c8 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,15 @@ +# Security Policy + +## Reporting a vulnerability + +Please **do not** open a public issue for security vulnerabilities. + +Preferred options: + +1. Use GitHub "Report a vulnerability" / Private Security Advisory (if enabled) +2. Email: **security@professoroakz.org** + +## Scope + +This policy covers security issues in repositories under the professoroakz organization, unless a +repo specifies a different policy. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..7591692 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,47 @@ +# Support + +## Getting Help + +If you need help with projects under the professoroakz organization: + +### 📚 Documentation + +- Check the repository's README for project-specific documentation +- Review the [organization profile](https://github.com/professoroakz) + +### 💬 Questions & Support + +- Use the repository's Issues section for questions +- Check existing issues before creating a new one + +### 🐛 Bug Reports + +- Use the bug report template in the repository's Issues section +- Provide detailed reproduction steps and environment information + +### 💡 Feature Requests + +- Use the feature request template in the repository's Issues section +- Explain the use case and expected behavior + +### 🔒 Security Issues + +- **Do not** create public issues for security vulnerabilities +- Follow the instructions in [SECURITY.md](SECURITY.md) + +## Contact + +- Email: security@professoroakz.org +- GitHub: [@professoroakz](https://github.com/professoroakz) + +## Response Times + +We aim to respond to: + +- Security issues: Within 48 hours +- Bug reports: Within 1 week +- Feature requests: Within 2 weeks +- General questions: Best effort basis + +_Note: Response times are not guaranteed as this is an open-source project maintained by +volunteers._ diff --git a/bin/github-config b/bin/github-config new file mode 100755 index 0000000..10b343a --- /dev/null +++ b/bin/github-config @@ -0,0 +1,140 @@ +#!/usr/bin/env bash +# GitHub Config CLI - Main entry point +# Usage: github-config [options] + +set -euo pipefail + +VERSION="1.3.37" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT_DIR="$(dirname "$SCRIPT_DIR")" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Helper functions +log_info() { + echo -e "${GREEN}[INFO]${NC} $*" +} + +log_warn() { + echo -e "${YELLOW}[WARN]${NC} $*" +} + +log_error() { + echo -e "${RED}[ERROR]${NC} $*" +} + +show_version() { + echo "github-config version $VERSION" +} + +show_help() { + cat << EOF +GitHub Config CLI v$VERSION + +Usage: github-config [options] + +Commands: + version Show version information + help Show this help message + validate Validate repository structure + install Install to system + info Show repository information + +Options: + -h, --help Show help + -v, --version Show version + +Examples: + github-config validate + github-config info + +EOF +} + +validate_repo() { + log_info "Validating repository structure..." + + required_files=( + "README.md" + "CODE_OF_CONDUCT.md" + "CONTRIBUTING.md" + "SECURITY.md" + "LICENSE" + ".github/ISSUE_TEMPLATE/bug_report.md" + ".github/ISSUE_TEMPLATE/feature_request.md" + ".github/pull_request_template.md" + ) + + missing=0 + for file in "${required_files[@]}"; do + if [[ -f "$ROOT_DIR/$file" ]]; then + log_info "✓ $file" + else + log_error "✗ $file (missing)" + missing=1 + fi + done + + if [[ $missing -eq 0 ]]; then + log_info "All required files present!" + return 0 + else + log_error "Some required files are missing" + return 1 + fi +} + +show_info() { + log_info "Repository Information:" + echo " Location: $ROOT_DIR" + echo " Version: $VERSION" + + if [[ -f "$ROOT_DIR/package.json" ]]; then + echo " NPM Package: @professoroakz/github" + fi + + if [[ -f "$ROOT_DIR/Dockerfile" ]]; then + echo " Docker Image: professoroakz/github-config" + fi +} + +install_system() { + log_info "Installing github-config to system..." + + # Create symlink in /usr/local/bin + if [[ -w /usr/local/bin ]]; then + ln -sf "$SCRIPT_DIR/github-config" /usr/local/bin/github-config + log_info "Installed to /usr/local/bin/github-config" + else + log_error "Cannot write to /usr/local/bin. Try with sudo." + return 1 + fi +} + +# Main command dispatcher +case "${1:-help}" in + version|-v|--version) + show_version + ;; + help|-h|--help) + show_help + ;; + validate) + validate_repo + ;; + info) + show_info + ;; + install) + install_system + ;; + *) + log_error "Unknown command: $1" + show_help + exit 1 + ;; +esac diff --git a/docker-compose.yml b/docker-compose.yml index 1d72b6d..2154d9b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -26,7 +26,7 @@ services: environment: - APP_VERSION=${VERSION:-1.3.37} healthcheck: - test: ["CMD", "test", "-f", "/app/VERSION"] + test: ['CMD', 'test', '-f', '/app/VERSION'] interval: 30s timeout: 3s retries: 3 @@ -34,8 +34,8 @@ services: networks: - github-network labels: - - "com.professoroakz.service=github-config" - - "com.professoroakz.version=${VERSION:-1.3.37}" + - 'com.professoroakz.service=github-config' + - 'com.professoroakz.version=${VERSION:-1.3.37}' networks: github-network: diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..c47e44f --- /dev/null +++ b/docs/API.md @@ -0,0 +1,323 @@ +# API Documentation + +Documentation for using the professoroakz/.github repository as a package. + +## NPM Package + +### Installation + +```bash +npm install @professoroakz/github +``` + +### Usage + +```javascript +const github = require('@professoroakz/github'); + +// Get package metadata +const metadata = github.getMetadata(); +console.log(metadata.version); // "1.3.37" +console.log(metadata.name); // "@professoroakz/github" +console.log(metadata.description); // Package description + +// List profile files +const profileFiles = github.listProfileFiles(); +// Returns: ['README.md', ...] + +// List settings files +const settingsFiles = github.listSettingsFiles(); +// Returns: ['.actions', ...] + +// Get path to a specific profile file +const profilePath = github.getProfilePath('README.md'); +// Returns: "/path/to/node_modules/@professoroakz/github/profile/README.md" + +// Get path to a specific settings file +const settingsPath = github.getSettingsPath('.actions'); +// Returns: "/path/to/node_modules/@professoroakz/github/settings/.actions" +``` + +## CLI Tool + +### Installation + +```bash +# From repository +cd .github +chmod +x bin/github-config +sudo ln -s $(pwd)/bin/github-config /usr/local/bin/github-config + +# Or use the installer +./bin/github-config install +``` + +### Commands + +#### validate + +Validate repository structure and required files. + +```bash +github-config validate +``` + +**Output:** + +``` +[INFO] Validating repository structure... +[INFO] ✓ README.md +[INFO] ✓ CODE_OF_CONDUCT.md +... +[INFO] All required files present! +``` + +#### info + +Show repository information. + +```bash +github-config info +``` + +**Output:** + +``` +[INFO] Repository Information: + Location: /path/to/.github + Version: 1.3.37 + NPM Package: @professoroakz/github + Docker Image: professoroakz/github-config +``` + +#### version + +Show version information. + +```bash +github-config version +``` + +**Output:** + +``` +github-config version 1.3.37 +``` + +#### help + +Show help message. + +```bash +github-config help +``` + +## Docker Image + +### Pull Image + +```bash +docker pull ghcr.io/professoroakz/github-config:latest +``` + +### Run Container + +```bash +# Interactive mode +docker run -it ghcr.io/professoroakz/github-config:latest + +# Run specific command +docker run --rm ghcr.io/professoroakz/github-config:latest node --version + +# Mount volume +docker run -v $(pwd):/workspace ghcr.io/professoroakz/github-config:latest +``` + +### Build Locally + +```bash +docker build -t professoroakz/github-config:local . +``` + +## Makefile + +### Targets + +#### install + +Install dependencies. + +```bash +make install +``` + +#### test + +Run test suite. + +```bash +make test +``` + +#### build + +Build the project. + +```bash +make build +``` + +#### clean + +Clean build artifacts. + +```bash +make clean +``` + +#### run + +Run the application. + +```bash +make run +``` + +#### docker-build + +Build Docker image. + +```bash +make docker-build +``` + +#### docker-run + +Build and run Docker container. + +```bash +make docker-run +``` + +#### lint + +Lint source files. + +```bash +make lint +``` + +#### format + +Format source files. + +```bash +make format +``` + +#### version-patch/minor/major + +Bump version. + +```bash +make version-patch # 1.0.0 -> 1.0.1 +make version-minor # 1.0.0 -> 1.1.0 +make version-major # 1.0.0 -> 2.0.0 +``` + +## Scripts + +### setup.sh + +Setup the repository environment. + +```bash +./scripts/setup.sh +``` + +### health-check.py + +Run health checks on repository. + +```bash +./scripts/health-check.py +``` + +### deploy.sh + +Deploy to various targets. + +```bash +# NPM +./scripts/deploy.sh npm + +# Docker +./scripts/deploy.sh docker + +# GitHub Release +./scripts/deploy.sh github-release + +# All targets +./scripts/deploy.sh all + +# Dry run +./scripts/deploy.sh --dry-run all +``` + +## Environment Variables + +### NPM_TOKEN + +NPM authentication token for publishing. + +```bash +export NPM_TOKEN=your_token_here +``` + +### GITHUB_TOKEN + +### GITHUB_TOKEN + +GitHub token for API access, releases, and GHCR authentication. + +```bash +export GITHUB_TOKEN=your_token_here +``` + +Note: This repository uses GitHub Container Registry (ghcr.io) for Docker images, which uses +GITHUB_TOKEN for authentication. + +## Error Handling + +All tools use exit codes to indicate success or failure: + +- `0` - Success +- `1` - General error +- `2` - Invalid arguments + +Example: + +```bash +if github-config validate; then + echo "Validation passed" +else + echo "Validation failed" + exit 1 +fi +``` + +## Versioning + +This package follows [Semantic Versioning](https://semver.org/). + +- **MAJOR**: Breaking changes +- **MINOR**: New features (backward compatible) +- **PATCH**: Bug fixes + +## Support + +For API questions or issues: + +- Check [SUPPORT.md](../SUPPORT.md) +- Open an issue on GitHub +- Review [CONTRIBUTING.md](../CONTRIBUTING.md) diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..4554334 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,355 @@ +# Frequently Asked Questions (FAQ) + +## General + +### What is this repository? + +This is the `.github` repository for the professoroakz organization. It contains default community +health files, issue templates, workflows, and configurations that apply to all repositories in the +organization. + +### How does the `.github` repository work? + +GitHub automatically uses files from a special `.github` repository as defaults for all public +repositories in an organization that don't have their own versions of these files. + +### Which files are shared across repositories? + +The following files are shared as defaults: + +- Issue templates (`.github/ISSUE_TEMPLATE/*`) +- Pull request template (`.github/pull_request_template.md`) +- CODE_OF_CONDUCT.md +- CONTRIBUTING.md +- SECURITY.md +- SUPPORT.md +- FUNDING.yml + +## Installation & Setup + +### How do I install this as an NPM package? + +```bash +npm install @professoroakz/github +``` + +### How do I use the CLI tool? + +```bash +# Clone the repository +git clone https://github.com/professoroakz/.github.git +cd .github + +# Install +./bin/github-config install + +# Or create a symlink manually +sudo ln -s $(pwd)/bin/github-config /usr/local/bin/github-config +``` + +### How do I run the setup script? + +```bash +./scripts/setup.sh +``` + +This will: + +- Check prerequisites +- Install dependencies +- Set permissions +- Validate structure +- Run tests + +## Usage + +### How do I validate my repository structure? + +```bash +# Using CLI tool +./bin/github-config validate + +# Using test script +./test/run-tests.sh + +# Using Python health check +./scripts/health-check.py +``` + +### How do I run tests? + +```bash +# NPM test +npm test + +# Test script +./test/run-tests.sh + +# Using Make +make test +``` + +### How do I build the Docker image? + +```bash +# Using Make +make docker-build + +# Using Docker directly +docker build -t professoroakz/github-config:latest . + +# Using deployment script +./scripts/deploy.sh docker +``` + +## Customization + +### Can I override these files in my repository? + +Yes! If you create the same file in your repository, it will override the default from this +`.github` repository. + +### How do I customize issue templates for my repository? + +1. Create `.github/ISSUE_TEMPLATE/` directory in your repository +2. Copy the templates you want to customize +3. Modify them for your needs +4. The customized templates will be used instead of the defaults + +### How do I add custom workflows? + +Workflows in this repository serve as templates and documentation. To use them: + +1. Copy the workflow to your repository's `.github/workflows/` directory +2. Customize as needed for your project +3. Commit and push + +Note: Workflows from the `.github` repository do NOT run automatically in other repositories. + +## Troubleshooting + +### The CLI tool isn't found + +Make sure it's executable and in your PATH: + +```bash +chmod +x bin/github-config +echo $PATH | grep -q "/usr/local/bin" || export PATH="/usr/local/bin:$PATH" +``` + +### NPM install fails + +Check your Node.js version: + +```bash +node --version # Should be >= 14.0.0 +npm --version +``` + +Update if needed: + +```bash +nvm install 20 +nvm use 20 +``` + +### Docker build fails + +Common issues: + +1. **Docker not running**: Start Docker daemon +2. **Permission denied**: Add user to docker group +3. **Out of disk space**: Clean up with `docker system prune` + +### Tests are failing + +Run the test suite: + +```bash +./test/run-tests.sh +``` + +Check for missing files: + +```bash +./bin/github-config validate +``` + +### Workflows aren't running + +Remember: + +- Workflows in `.github` repository are templates/documentation +- They don't run automatically in other repositories +- Copy them to your repository's `.github/workflows/` to use + +## Development + +### How do I contribute? + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed guidelines. + +Quick steps: + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Run tests +5. Submit a pull request + +### How do I add a new feature? + +1. Open an issue first to discuss +2. Follow coding standards +3. Add tests for new functionality +4. Update documentation +5. Submit PR with all checks passing + +### How do I report a bug? + +Use the bug report template: + +1. Go to Issues tab +2. Click "New Issue" +3. Select "Bug report" +4. Fill in all sections +5. Submit + +## Security + +### How do I report a security vulnerability? + +**DO NOT** open a public issue. Instead: + +1. Use GitHub's "Report a vulnerability" feature +2. Or email: security@professoroakz.org + +See [SECURITY.md](../SECURITY.md) for details. + +### Are dependencies kept up to date? + +Yes, through: + +- Dependabot (automated PRs for updates) +- Renovate (optional, more advanced automation) +- Regular security audits + +## Performance + +### Is this package lightweight? + +Yes: + +- Minimal dependencies +- Small package size +- Fast installation +- Efficient Docker images + +### What are the system requirements? + +**Minimum:** + +- Node.js 14+ (for NPM package) +- Bash 4+ (for scripts) +- Python 3.6+ (for Python scripts) + +**Recommended:** + +- Node.js 20+ +- Docker (for containerization) +- Make (for build automation) + +## Integration + +### Can I use this with GitHub Actions? + +Yes! The repository includes several workflow templates you can copy to your repository. + +### Can I use this with other CI/CD systems? + +Yes, the scripts and tools work independently of GitHub Actions and can be integrated with: + +- GitLab CI +- Jenkins +- CircleCI +- Travis CI +- Any CI/CD system that supports Bash/Node.js + +### Can I deploy to other registries? + +Yes, modify the deployment script or workflows to target: + +- Private NPM registries +- Docker registries (Docker Hub, AWS ECR, etc.) +- Other package managers + +## Support + +### Where can I get help? + +1. Check this FAQ +2. Read documentation in `docs/` +3. Search existing issues +4. Open a new issue +5. See [SUPPORT.md](../SUPPORT.md) + +### How do I request a feature? + +1. Check if it's already requested +2. Use the feature request template +3. Explain the use case +4. Provide examples + +### Is there a community chat? + +Check the organization's main page for: + +- Discussions (if enabled) +- Chat links +- Community resources + +## Licensing + +### What license is this under? + +MIT License - see [LICENSE](../LICENSE) file. + +### Can I use this in commercial projects? + +Yes, the MIT license allows commercial use. + +### Do I need to give attribution? + +Attribution is appreciated but not required by the MIT license. + +## Updates + +### How often is this updated? + +- Security updates: As needed +- Dependency updates: Weekly (automated) +- Feature updates: As developed +- Documentation: Ongoing + +### How do I stay informed about updates? + +- Watch the repository +- Enable notifications +- Check CHANGELOG.md +- Follow releases + +### Will updates break my code? + +We follow semantic versioning: + +- PATCH: Bug fixes (safe) +- MINOR: New features (safe, backward compatible) +- MAJOR: Breaking changes (review before upgrading) + +## Additional Resources + +- [Installation Guide](INSTALLATION.md) +- [Workflows Documentation](WORKFLOWS.md) +- [Templates Guide](TEMPLATES.md) +- [Guidelines](GUIDELINES.md) +- [API Documentation](API.md) diff --git a/docs/GUIDELINES.md b/docs/GUIDELINES.md new file mode 100644 index 0000000..7335a3d --- /dev/null +++ b/docs/GUIDELINES.md @@ -0,0 +1,232 @@ +# Guidelines for professoroakz Repositories + +General guidelines that apply to all repositories under the professoroakz organization. + +## Code of Conduct + +All repositories follow the Contributor Covenant Code of Conduct. See +[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md). + +Key principles: + +- Be respectful and inclusive +- Welcome newcomers +- Accept constructive criticism +- Focus on what's best for the community + +## Contributing + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed contribution guidelines. + +## Security + +Report security vulnerabilities privately. See [SECURITY.md](../SECURITY.md). + +## Git Workflow + +### Branch Naming + +Use descriptive branch names with prefixes: + +- `feat/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation changes +- `chore/` - Maintenance tasks +- `refactor/` - Code refactoring +- `test/` - Test additions or changes + +Examples: + +- `feat/add-user-authentication` +- `fix/resolve-memory-leak` +- `docs/update-installation-guide` + +### Commit Messages + +Follow conventional commits format: + +``` +(): + + + +