From e4e5bea37beb4ee617f572ce89f00758a6ac59c1 Mon Sep 17 00:00:00 2001 From: Mohammad Shafiee Date: Mon, 20 Jul 2026 23:28:47 +0200 Subject: [PATCH] Cross-cutting: org templates, governance, and reusable lint workflow - ISSUE_TEMPLATE/{bug_report,feature_request}.yml + config.yml (blank issues off; contact links to website/spec/security). Bilingual note. - PULL_REQUEST_TEMPLATE.md: spec-alignment + hard-constraint checklist. - CONTRIBUTING.md: repo map, conventions, branch model, lint opt-in pattern. - CODE_OF_CONDUCT.md: Contributor Covenant 2.1 (conduct@zurvanlinux.org). - SECURITY.md: private reporting (GH Private Vuln Reporting / encrypted email), signing-key integrity + rotation pointer. - .github/workflows/lint.yml: reusable workflow_call running shellcheck + yamllint (tolerant Actions-tuned config) and an astro check/build job gated on the presence of astro.config.*. - profile/README.md: Status updated from 'spec only' to Phase 1 in progress. - README.md: documents the org-level files and the lint opt-in snippet. --- .github/workflows/lint.yml | 94 ++++++++++++++++++++++++++++++ CODE_OF_CONDUCT.md | 67 +++++++++++++++++++++ CONTRIBUTING.md | 72 +++++++++++++++++++++++ ISSUE_TEMPLATE/bug_report.yml | 53 +++++++++++++++++ ISSUE_TEMPLATE/config.yml | 11 ++++ ISSUE_TEMPLATE/feature_request.yml | 45 ++++++++++++++ PULL_REQUEST_TEMPLATE.md | 21 +++++++ README.md | 29 ++++++++- SECURITY.md | 45 ++++++++++++++ profile/README.md | 10 +++- 10 files changed, 445 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/lint.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 ISSUE_TEMPLATE/bug_report.yml create mode 100644 ISSUE_TEMPLATE/config.yml create mode 100644 ISSUE_TEMPLATE/feature_request.yml create mode 100644 PULL_REQUEST_TEMPLATE.md create mode 100644 SECURITY.md diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..69927d1 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,94 @@ +name: Lint (reusable) + +# Reusable lint workflow called by individual repos via: +# jobs: +# lint: +# uses: ZurvanLinux/.github/.github/workflows/lint.yml@main +# Runs in the CALLER repo's context (it lints the caller's files). + +on: + workflow_call: + +permissions: + contents: read + +jobs: + lint: + name: shellcheck + yamllint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install linters + run: | + set -eux + sudo apt-get update + sudo apt-get install -y shellcheck yamllint + + - name: shellcheck + run: | + set -e + # Discover shell scripts: *.sh, the live-build auto/ directory, and any + # file whose first line is a sh/bash/dash shebang. + files=$( { + find . -type f \( -name '*.sh' -o -path './auto/*' \) -not -path './.git/*' -not -path './node_modules/*'; + grep -rIl --include='*' -E '^#![[:space:]]*/[^[:space:]]*/(env[[:space:]]+)?(sh|bash|dash)([[:space:]]|$)' . 2>/dev/null \ + | grep -v -e '^./.git/' -e '^./node_modules/'; + } | sort -u ) + if [ -z "$files" ]; then + echo "No shell scripts found; skipping shellcheck." + exit 0 + fi + echo "Linting:"; echo "$files" + # SC2312: "consider invoking grep without cat" is noise for scripts we own. + echo "$files" | xargs shellcheck --external-sources --format=gcc --exclude=SC2312 + + - name: yamllint + run: | + set -e + # Tolerant config tuned for GitHub Actions YAML (line length off; the + # workflow `on:` key would trip truthy, so check-keys is off). + files=$(find . -type f \( -name '*.yml' -o -name '*.yaml' \) \ + -not -path './.git/*' -not -path './node_modules/*') + if [ -z "$files" ]; then + echo "No YAML files found; skipping yamllint." + exit 0 + fi + echo "Linting:"; echo "$files" + echo "$files" | xargs yamllint -d '{extends: default, + rules: { + line-length: disable, + document-start: disable, + indentation: disable, + comments: disable, + comments-indentation: disable, + truthy: {check-keys: false}, + new-line-at-end-of-file: disable + }}' + + astro: + name: astro check + build + runs-on: ubuntu-latest + # Only runs in repos that actually have an Astro config (e.g. website). + if: ${{ hashFiles('astro.config.mjs', 'astro.config.*', 'astro.config.ts') != '' }} + env: + ASTRO_TELEMETRY_DISABLED: '1' + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + + - name: Install dependencies + run: npm ci + + - name: astro check + run: npm run check + + - name: astro build + run: npm run build diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f1238da --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,67 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of + any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +**conduct@zurvanlinux.org**. All complaints will be reviewed and investigated +promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +. + +[homepage]: https://www.contributor-covenant.org + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6f14cde --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to Zurvan Linux + +نوشته‌های زیر را می‌توانید به فارسی یا انگلیسی بخوانید؛ مشارکت در هر دو زبان ممکن است. First: thank you for helping build a Persian-first Debian distribution. + +## Read the spec first + +The five documents in [`ZurvanLinux/ZurvanLinux`](https://github.com/ZurvanLinux/ZurvanLinux) are the source of truth: + +| Doc | Covers | +|-----|--------| +| `technical-spec-architecture.md` | Architecture, kernel/driver stack, desktop, Calamares | +| `package-manifest.md` | Exact pre-installed apt/flatpak/codec/font packages | +| `ui-ux-localization-plan.md` | Vazirmatn, RTL, ISIRI 9147 keyboard, Jalali | +| `distribution-update-strategy.md` | ISO delivery, APT repo, GPG signing | +| `testing-qa-checklist.md` | Release-validation checklist (the release gate) | + +Also read [`AGENTS.md`](https://github.com/ZurvanLinux/ZurvanLinux/blob/main/AGENTS.md) for the **hard constraints** (Debian 13 `amd64`-only in Phase 1, Plasma 6.7 Wayland-default, `contrib`/`non-free`/`non-free-firmware` on, Vazirmatn fontconfig, ISIRI 9147 + ZWNJ on `Shift+Space`, `Asia/Tehran` + Jalali). Do not deviate without opening a discussion issue first. + +## Where things live + +| Repo | What belongs here | +|------|-------------------| +| `ZurvanLinux` | Spec docs (prose changes only) | +| `iso-builder` | `live-build` config + the ISO build pipeline | +| `apt-repository` | `pool/` of `.deb`s + the publish/signing workflow | +| `website` | Astro landing page | +| `branding-assets` | Wallpapers, themes, icons | +| `zurvan-dns-bypass` | The DNS-switcher source + packaging | +| `welcome-app` | First-boot welcome assistant | +| `.github` | This file, org templates, reusable lint workflow | + +## How to propose a change + +1. **Open an issue first** for anything beyond a trivial fix — especially anything that touches a spec doc or a hard constraint. Use the bug/feature templates. +2. **Branch from `main`** using `feat/...`, `fix/...`, `docs/...`, or `chore/...`. Trunk-based; keep branches short-lived. +3. **Open a pull request** against `main`. Fill in the PR template checklist. For Phase 1 (solo + AI agents) PRs are not hard-enforced but are the convention and the review record. +4. **Keep diffs focused.** One logical change per PR. If you touch a hard constraint, call it out explicitly in the PR description. + +## Coding conventions + +- **Shell:** POSIX-friendly where possible (`sh`), `bash` only when needed. `set -eu`. Lint with `shellcheck` (the reusable `lint` workflow runs it). +- **Workflows (YAML):** pin Actions to a major (`@v4`) or SHA; validate with `yamllint` (reusable `lint` workflow). +- **Astro / TypeScript:** `astro check` must pass with 0 errors. +- **No secrets in code.** Use repository / org secrets for credentials. +- **Bilingual UX copy:** Persian is the source language; mirror in English via `src/i18n/ui.ts` on the website. Use ZWNJ (نیم‌فاصله) correctly in Persian text. + +## Lint locally + +The reusable workflow in this repo (`ZurvanLinux/.github/.github/workflows/lint.yml`) runs `shellcheck` + `yamllint` (+ an Astro build check on the website). To opt a repo in, add a tiny caller: + +```yaml +# .github/workflows/lint.yml +name: Lint +on: { push: { branches: [main] }, pull_request: {} } +jobs: + lint: + uses: ZurvanLinux/.github/.github/workflows/lint.yml@main +``` + +## Testing + +- **ISO:** changes to `iso-builder` should produce a green `build-iso.yml` run and boot to a login prompt in QEMU (see that repo's README). +- **Website:** `npm run check` + `npm run build` must pass; verify RTL/LTR on both locales. +- **APT repo:** `publish-repo.yml` must regenerate indices cleanly; signing requires the P0 secrets. + +## Licensing + +Each repository declares its own license in its `LICENSE` file. By contributing, you agree your contributions are licensed under that repository's license. The spec docs are CC-BY-SA-4.0; code is GPL-compatible per repo. + +## Questions? + +Open a `triage` issue, or start a discussion once Phase 1 ships Discussions (planned for Phase 5). For security matters, see [`SECURITY.md`](./SECURITY.md). diff --git a/ISSUE_TEMPLATE/bug_report.yml b/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..673992e --- /dev/null +++ b/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,53 @@ +name: 🐛 Bug report +description: Report something that is broken or behaves incorrectly. +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug! \ + می‌توانید این گزارش را به فارسی یا انگلیسی پر کنید. لطفاً تا حد امکان تصاویر یا خروجی ترمینال را ضمیمه کنید. + - type: dropdown + id: component + attributes: + label: Component / repo + options: + - iso-builder (ISO build / live image) + - apt-repository + - website + - branding-assets + - zurvan-dns-bypass + - welcome-app + - ZurvanLinux (spec docs) + - other + validations: + required: true + - type: input + id: version + attributes: + label: ISO / package version (if applicable) + placeholder: "e.g. v0.2.0-pre.3, or git commit SHA" + - type: textarea + id: what-happened + attributes: + label: What happened? + description: A clear description of the bug and what you expected instead. + placeholder: "Steps to reproduce: 1. ... 2. ... Expected: ... Actual: ..." + validations: + required: true + - type: textarea + id: env + attributes: + label: Environment + description: How you ran it. Include as much as helps us reproduce. + placeholder: | + - Boot mode: BIOS / UEFI / Secure Boot + - VM or hardware: e.g. QEMU 8, VirtualBox 7, Intel NUC + - GPU: e.g. Intel UHD, AMD Renoir, NVIDIA + - Language/layout: fa / en, keyboard toggle, ZWNJ + - type: textarea + id: logs + attributes: + label: Logs / screenshots + description: Output of `journalctl -b`, `dmesg`, screenshots, or installer logs. Paste between the triple backticks. + render: shell diff --git a/ISSUE_TEMPLATE/config.yml b/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..34553fe --- /dev/null +++ b/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: 🌐 Website + url: https://zurvanlinux.org + about: Zurvan Linux landing page (Persian / English). + - name: 📖 Specification & architecture docs + url: https://github.com/ZurvanLinux/ZurvanLinux + about: The authoritative spec set (technical-spec, package-manifest, ui-ux, distribution, qa-checklist). + - name: 🔒 Report a security vulnerability + url: https://github.com/ZurvanLinux/.github/blob/main/SECURITY.md + about: Do not open public issues for security problems — follow the disclosure process. diff --git a/ISSUE_TEMPLATE/feature_request.yml b/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..62f4026 --- /dev/null +++ b/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,45 @@ +name: ✨ Feature request +description: Suggest an idea, package, or improvement. +labels: ["enhancement", "triage"] +body: + - type: markdown + attributes: + value: | + Tell us what you'd like to see. \ + این فرم را می‌توانید به فارسی یا انگلیسی تکمیل کنید. + - type: textarea + id: problem + attributes: + label: The problem + description: What is currently hard or impossible to do? + validations: + required: true + - type: textarea + id: solution + attributes: + label: Your proposed solution + description: What you'd like to happen, and any alternatives you've considered. + validations: + required: true + - type: dropdown + id: component + attributes: + label: Component / repo + options: + - iso-builder + - apt-repository + - website + - branding-assets + - zurvan-dns-bypass + - welcome-app + - ZurvanLinux (spec docs) + - other + validations: + required: true + - type: checkboxes + id: scope + attributes: + label: Scope check + options: + - label: This aligns with the Zurvan Linux spec (see ZurvanLinux/ZurvanLinux) and isn't a Phase 2+ deferred fork. + required: false diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..b4bcb43 --- /dev/null +++ b/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ + + +## Summary + + + +## Related issue + + + +## Checklist + +- [ ] The change follows the relevant spec doc (`technical-spec-architecture.md` / `package-manifest.md` / `ui-ux-localization-plan.md` / `distribution-update-strategy.md` / `testing-qa-checklist.md`), or I have flagged a divergence for discussion. +- [ ] Hard constraints respected (Debian 13 amd64-only in Phase 1; Plasma 6.7 Wayland-default; non-free repos on; Vazirmatn fontconfig; ISIRI 9147 + ZWNJ on `Shift+Space`; Asia/Tehran + Jalali). +- [ ] Persian copy (where user-visible) is correct and uses ZWNJ where needed; RTL layout verified. +- [ ] Workflows pass (`build-iso.yml`, `publish-repo.yml`, `deploy-site.yml`, or `lint` as relevant). +- [ ] No secrets, private keys, or personal data committed. + +## Notes for reviewers + + diff --git a/README.md b/README.md index 02ae951..357a8fa 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,29 @@ # .github -Zurvan Linux org profile, issue/PR templates, and contribution guidelines + +Organization-level files for **Zurvan Linux**: + +- `profile/README.md` — the org profile shown on . +- `ISSUE_TEMPLATE/` — default bug-report / feature-request forms (`config.yml` points to the website, spec docs, and security policy; blank issues are disabled). +- `PULL_REQUEST_TEMPLATE.md` — PR checklist (spec alignment + hard-constraint reminders + bilingual note). +- `CONTRIBUTING.md` — how to contribute, repo map, conventions, and the opt-in lint pattern. +- `CODE_OF_CONDUCT.md` — Contributor Covenant 2.1. +- `SECURITY.md` — private vulnerability reporting process + signing-key integrity notes. +- `.github/workflows/lint.yml` — **reusable** lint workflow (`shellcheck` + `yamllint`, plus an Astro `check`/`build` job for repos with an `astro.config`). + +## Opting a repo into the reusable lint + +Add a tiny caller workflow in the target repo: + +```yaml +# .github/workflows/lint.yml +name: Lint +on: + push: + branches: [main] + pull_request: +jobs: + lint: + uses: ZurvanLinux/.github/.github/workflows/lint.yml@main +``` + +See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full contributor guide. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..de91d8c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,45 @@ +# Security policy + +## Reporting a vulnerability + +Please **do not open a public GitHub issue** for security problems. + +Instead, report vulnerabilities privately: + +1. Prefer **GitHub Private Vulnerability Reporting**: go to the relevant repo → + **Security** → **Report a vulnerability**. (Enable it on the repo if missing.) +2. Or email **security@zurvanlinux.org**. If you can, encrypt with the Zurvan + Linux archive GPG key published at + (fingerprint in the same key). + The P0 GPG key is generated offline; until it is published, email is the + fallback channel. + +Please include: + +- Affected component/repo and version (ISO tag, package version, or commit SHA). +- A clear description and proof of concept or reproduction steps. +- Your assessment of impact and any suggested remediation. + +## Response targets (best-effort, Phase 1) + +- Acknowledgement: within **3 business days**. +- Initial assessment and a coordination plan: within **7 business days**. +- Coordinated disclosure after a fix is available (or after 90 days, per + standard responsible-disclosure convention, whichever comes first). + +## Scope + +In scope: the installed system (kernel/driver/firmware configuration shipped by +the ISO), the APT repository integrity (Release/InRelease signing), the +Calamares configuration, the `zurvan-dns-bypass` mechanism, the welcome app, and +the website. Out of scope: vulnerabilities in upstream Debian/KDE/Flatpak +packages themselves — report those to the upstream project or Debian's security +team. + +## Signing key integrity + +The custom APT repository is signed by a 4096-bit GPG key whose primary is held +**offline**; only a signing subkey is used in CI. See +[`apt-repository/README.md`](https://github.com/ZurvanLinux/apt-repository#signing-key-rotation-runbook) +for the rotation runbook. If you suspect the signing subkey has been compromised, +report it immediately via the channels above so the subkey can be revoked. diff --git a/profile/README.md b/profile/README.md index 475d7d7..79e0d06 100644 --- a/profile/README.md +++ b/profile/README.md @@ -30,7 +30,15 @@ The full specification lives in [`ZurvanLinux/ZurvanLinux`](https://github.com/Z ## Status -**Phase 1 — specification only.** No source code, ISO images, or packages are published yet. Implementation begins once the spec set is finalized. +**Phase 1 — implementation in progress.** The infrastructure is landing: + +- ✅ `iso-builder` — minimal ISO proof build pipeline (live-build in a privileged `debian:trixie` container; boots to a login prompt in QEMU). Full KDE baseline (M1.1b) next. +- ✅ `apt-repository` — signed APT repo skeleton + publish/signing workflow (live once the offline GPG key + secrets are configured — a P0 prerequisite). +- ✅ `website` — Persian-first Astro landing page; deploys to GitHub Pages (live at `zurvanlinux.org` once Cloudflare DNS + HTTPS are configured). + +**P0 (maintainer-owned) still pending:** offline GPG primary key + signing subkey + repo secrets, and Cloudflare DNS (`apex`/`www`/`repo`/`download`) + Pages HTTPS enforcement. Until then, `repo.zurvanlinux.org` and `zurvanlinux.org` resolve only over the GitHub Pages hostnames. + +No stable ISO or `.deb` packages are published yet — those follow in Phase 2–5. ## Links