diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a47abaa..8e4d65c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,183 +1,24 @@ -# Contributing to Agiletec Inc. +# Contribution guide -Thank you for your interest in contributing to Agiletec Inc. and our vision. +agiletec-incの公開projectへのIssue・Pull Requestを歓迎します。変更対象repoのREADME、license、security policy、 +contribution guideを先に確認してください。 -## 🎯 Our Mission +## Issue -**Eliminate the multi-tier subcontracting structure.** +再現手順、期待結果、実際の結果、version・OSなど必要な環境情報を記載してください。security vulnerabilityは +public Issueへ書かず[`SECURITY.md`](./SECURITY.md)のprivate reporting channelを使ってください。 -We solve structural inefficiencies in Japan's IT industry and realize a future where all companies have in-house development capabilities. +## Pull Request ---- +- 一つの責務へ絞り、関連Issueと変更理由を示す。 +- repoのformat、lint、typecheck、testを実行し、実commandと結果を書く。 +- user-visible behaviorや運用境界を変える場合だけ、正本の文書を同時に更新する。 +- generated file、secret、credential、customer dataをcommitしない。 +- 既存codeの命名、comment密度、architectureへ合わせる。 -## 🤝 How to Contribute +reviewではcorrectness、security、互換性、scope、検証可能性を確認します。変更依頼へ対応後、required checksが +greenになればmaintainerがmergeします。 -### 1. Contributing to Open Source Projects +## License -#### Our Projects - -Open source projects developed and maintained by Agiletec Inc.: - -- **[AIRIS MCP Gateway](https://github.com/agiletec-inc/airis-mcp-gateway)** - MCP integrated gateway -- **[mindbase](https://github.com/agiletec-inc/mindbase)** - AI conversation knowledge management -- **[superagent](https://github.com/agiletec-inc/superagent)** - Claude Code enhancement framework -- **[airis-translate](https://github.com/agiletec-inc/airis-translate)** - Native macOS translation tool -- **[selfhosted-supabase-mcp](https://github.com/agiletec-inc/selfhosted-supabase-mcp)** - Supabase MCP server -- **[cmd-ime](https://github.com/agiletec-inc/cmd-ime)** - macOS input method switcher - -#### Projects We Contribute To - -Open source projects we actively contribute to: - -- **[SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework)** - AI development framework - -Please refer to each project's `CONTRIBUTING.md` for specific guidelines. - ---- - -### 2. Issue Reporting - -Bug reports and feature requests are accepted through each project's Issues. - -**Good Issue Examples**: -- Clear reproduction steps -- Description of expected vs actual behavior -- Environment information (OS, version, etc.) - ---- - -### 3. Pull Requests - -**Contribution Flow**: - -1. **Fork**: Fork the project -2. **Branch**: Create a `feature/your-feature-name` branch -3. **Implement**: Implement code changes -4. **Test**: Add and run tests -5. **Commit**: Follow [Conventional Commits](https://www.conventionalcommits.org/) -6. **Push**: Push to your fork -7. **PR**: Create Pull Request to the original repository - -**Commit Message Format**: -``` -feat: add new API endpoint for user management -fix: correct authentication token validation -docs: update README installation section -chore: update dependencies -refactor: simplify error handling logic -``` - ---- - -### 4. Code Standards - -#### General Principles -- **SOLID**: Single Responsibility, Open/Closed, Liskov Substitution -- **DRY**: Don't Repeat Yourself -- **YAGNI**: You Aren't Gonna Need It -- **KISS**: Keep It Simple, Stupid - -#### TypeScript/JavaScript -- Follow ESLint + Prettier configuration -- Explicit type definitions -- Comments explain WHY, not WHAT - -#### Python -- Follow Black + Ruff configuration -- Type hints required (Python 3.12+) -- Docstrings (Google Style) - ---- - -### 5. Documentation - -**Required Documentation**: -- `README.md`: Project overview, installation instructions -- `ARCHITECTURE.md`: Technical architecture (complex projects only) -- `CHANGELOG.md`: Version history -- Inline Comments: Explain complex logic - -**Documentation Principles**: -- English preferred (technical terms in English) -- Include examples -- Keep up to date - ---- - -## 💡 Contribution Ideas - -### Beginner-Friendly -- Fix documentation typos -- Add sample code -- Translations (English ↔ Japanese) -- Improve test coverage - -### Intermediate -- Bug fixes -- New feature implementation -- Performance improvements -- Refactoring - -### Advanced -- Architecture improvements -- Security enhancements -- Scalability improvements -- New product proposals - ---- - -## 🛡️ Security - -If you discover a security vulnerability, **do not create a public issue**. Please contact us directly: - -📧 **security@agiletec.net** - -See [SECURITY.md](./SECURITY.md) for details. - ---- - -## 📋 Code Review Process - -1. **Automated Checks**: CI/CD (lint, test, build) must pass -2. **Code Review**: Maintainers review within 1-3 business days -3. **Feedback**: Comments if changes are requested -4. **Approval**: Merge after approval - -**Review Criteria**: -- Code quality -- Test coverage -- Documentation clarity -- Alignment with vision - ---- - -## 🌟 Recognition - -Contributors are recognized through: -- Listed in project's `CONTRIBUTORS.md` -- Acknowledged in release notes -- Special thanks for significant contributions - ---- - -## 🤔 Questions? - -If you have questions, feel free to reach out: - -- **GitHub Discussions**: Each project's Discussions -- **Email**: hello@agiletec.net -- **X (Twitter)**: [@agiletec_inc](https://x.com/agiletec_inc) - ---- - -## 📄 License - -Contributed code follows each project's license (typically MIT License). - ---- - -**Thank you for your cooperation!** - -Let's move forward together to realize our vision of "in-house development for every company." - -— Agiletec Inc. Team +contributionには対象repoのlicenseが適用されます。 diff --git a/policies/ci-cd-standardization-status.md b/policies/ci-cd-standardization-status.md deleted file mode 100644 index ab087cf..0000000 --- a/policies/ci-cd-standardization-status.md +++ /dev/null @@ -1,123 +0,0 @@ -# CI/CD Standardization — Status & Remediation - -Companion to [`ci-cd-trigger-strategy.md`](./ci-cd-trigger-strategy.md) (the policy / SSoT). -That document defines the **target**; this one tracks **how far each repo has actually -adopted it** and the prioritized work to close the gaps. - -**Snapshot: 2026-06-10** (regenerate by re-surveying `*/.github/workflows/`). - -## Enforcement model decision (2026-06-10) - -org plan = **`team`**. The ruleset rule "Require workflows to pass before merging" -(auto-injects a gate into every repo, no per-repo file) is **Enterprise Cloud only** and -does not run on Team. Decision: **stay on Team** and enforce CI org-wide via the -**"Require status checks to pass"** ruleset rule (Team-available) + standardized check -names (`secret-scan / scan`, `ci / ci`) + thin per-repo callers from the org reusables. - -**Targeting = custom property** (GitHub Well-Architected recommendation, not repo-name -lists): org custom property `ci_managed` (true_false) + ruleset "Org CI required checks" -(id 17507867) filtering on `props.ci_managed:true`. A repo enrolls by setting the property; -the ruleset definition never changes. New repos: starter workflow + property. Existing -repos: per-repo reviewed migration PR, then set the property. See -`ci-cd-trigger-strategy.md` § Org-wide enforcement model. - -## Summary - -| Area | State | -|---|---| -| Policy / SSoT (`ci-cd-trigger-strategy.md`) | ✅ done | -| Reusable workflows (`secret-scan`, `node-pnpm-ci`, `rust-cargo-ci`, `python-ci`, `swift-ci`, `docker-publish`, `auto-merge`) | ✅ exist (multi-lang as of 2026-06-10) | -| Reusable actions SHA-pinned (in `.github` repo) | ✅ done + Dependabot bumps | -| Starter templates (`workflow-templates/`) | ✅ added (node/rust/python/swift) | -| Custom property `ci_managed` + property-targeted ruleset (id 17507867) | ✅ created (active) | -| Reusable **adoption** across repos | ⚠️ thin — migrate per-repo (see matrix), then set `ci_managed=true` | -| Pilot enrolled (`airis-keeper`, `ci_managed=true`, gated) | ✅ done | -| Public repos on release-driven CD | ✅ done (cmd-ime / airis-mcp-gateway reference impls) | -| Private (agiletec / agile-server) release-driven migration | ❌ TODO (plan 520 Step 5–9) | -| Runner labels unified | ❌ fragmented (4 self-hosted labels) | -| Action SHA-pinning enforced org-wide (consumer repos) | ⚠️ partial — reusables pinned; consumers via migration | - -## Reusable-workflow adoption matrix - -Which repos **call** each org reusable (`uses: agiletec-inc/.github/.github/workflows/.yml@…`): - -| Reusable | Callers (2026-06-10) | Note | -|---|---|---| -| `secret-scan.yml` | `mail-cleanse` | only adopter; should be a **required check everywhere** | -| `node-pnpm-ci.yml` | `airis-code` | most Node/Bun repos still hand-roll `ci.yml` | -| `docker-ghcr-publish.yml` | `mindbase` | GHCR pushers (airis-mcp-gateway/voom) still bespoke | -| `auto-merge.yml` | `airis-mcp-gateway`, `mindbase` | — | - -**Gap**: the majority of repos (`agiletec`, `agile-server`, `airis-studio`, `cmd-ime`, -`voom`, `airis-mcp-gateway` CI, …) carry **duplicated bespoke workflows** instead of -calling the reusables. Every duplicate is a place a fix has to be applied N times. - -## Runner-label inventory - -Self-hosted labels in use (approx. `runs-on:` occurrences across all repos): - -| Label | Kind | ~uses | Owner | -|---|---|---|---| -| `airis-studio-runners` | ARC | 19 | airis-studio (GPU build) | -| `agiletec-ci-runner` | ARC | 17 | agiletec | -| `agile-server-runner` | ARC | 8 | agile-server | -| `agiletec-self-hosted-runner` | ARC | 7 | org default (per policy) | -| `ubuntu-latest` / `ubuntu-22.04` / `macos-*` | GitHub-hosted | 45+ | public repos | - -**Gap**: four distinct self-hosted labels with overlapping purpose. Policy names -`agiletec-self-hosted-runner` as the private default, but `agiletec-ci-runner` is used -more. Target: consolidate to ARC **runner scale sets** with multilabel (ARC ≥0.14.0), -namespace-isolated, with a small canonical label set (e.g. one general private label + -dedicated labels only where hardware differs, e.g. GPU for airis-studio). - -## Action SHA-pinning - -- **Status**: not enforced. Most workflows reference mutable tags (`@v4`, `@v2`). -- **Target** (official best practice): pin every action to a **full commit SHA** with a - trailing `# vX` comment; let Dependabot (`github-actions` ecosystem) bump them. -- **Enforcement**: enable the org **allowed-actions SHA-pinning policy** - (Settings → Actions → Policies) so unpinned actions fail. Watch the 2026 roadmap - workflow-dependency lockfile. -- Reference impl: `mail-cleanse/.github/workflows/ci.yml` (checkout/setup-bun SHA-pinned, - `permissions: contents: read`). - -## Registry split (intentional, keep) - -| Registry | Repos | Auth | -|---|---|---| -| GHCR | `airis-mcp-gateway`, `voom`, `mindbase` | `GITHUB_TOKEN` + `docker/login-action`, `permissions: packages: write` (no OIDC needed) | -| Zot (in-cluster) | `agiletec`, `airis-studio`, `duplicate-finder` | cluster registry creds | - -OIDC is **not required for GHCR**; reserve it for external cloud (e.g. AWS). Current -near-zero OIDC usage is fine. - -## Private release-driven migration - -- **Status**: ❌ not done. `agiletec/_build-image.yml` still bumps the deploy repo on - every main push (legacy continuous-deploy). Public repos already migrated. -- **Tracked in**: `~/.claude/plans/520-reach-bit-alert-auto-squishy-allen.md` (Step 5–9: - `release-deploy.yml`, `environment: prd` reviewer gate, `_build-image.yml` bump removal). -- High-risk (touches prod deploy + cross-repo GitHub App). Execute as a dedicated effort. - -## Remediation checklist (prioritized) - -- [x] **Pilot** (`airis-keeper`): caller PR #4, checks `secret-scan / scan` + `ci / ci` green, - public→hosted routing confirmed. -- [x] **Custom property + ruleset**: `ci_managed` (true_false) + ruleset id 17507867 (active) - targeting `props.ci_managed:true`. airis-keeper enrolled. - -1. **Migrate bespoke `ci.yml` per repo** (reviewed PRs, airis-keeper pattern — validate - package manager / run-command / green). Then set `ci_managed=true` on that repo to enroll. - Order: voom / mail-cleanse / cmd-ime / duplicate-finder / airis-workspace / mindbase / - airis-mcp-gateway / mcp (`rust-cargo-ci` / `python-ci` / `swift-ci` / `node-pnpm-ci`). -2. **New repos**: starter workflow (1-click) + `ci_managed=true`. -3. **Heavy bespoke repos** (agiletec / airis-studio / agile-server): leave `ci_managed` unset - (excluded), or make their CI emit `ci` / `secret-scan` check names before enrolling. -4. **SHA-pin actions in consumer repos** + add Dependabot `github-actions` (the `.github` - reusables are already pinned + Dependabot-tracked). -5. **Private release-driven migration** (plan 520 Step 5–9) for agiletec / agile-server. -6. **Runner-label consolidation** via ARC runner scale sets (cluster change → agile-server - GitOps PR). - -Items 1–4 are low-risk (incremental PRs). Items 5–6 touch prod / the cluster and need -dedicated, separately-approved efforts. diff --git a/policies/ci-cd-trigger-strategy.md b/policies/ci-cd-trigger-strategy.md index d515020..3f41edb 100644 --- a/policies/ci-cd-trigger-strategy.md +++ b/policies/ci-cd-trigger-strategy.md @@ -120,27 +120,6 @@ not optional decoration. pattern (`.env`, `.env.local`, `.env.*`, `*.pem`, `*credentials*`) - Dependabot enabled (free, default for public) -## Implementation status (2026-06-12) - -> Per-repo adoption status, gap analysis, and the prioritized remediation -> checklist live in the companion doc -> [`ci-cd-standardization-status.md`](./ci-cd-standardization-status.md). - -- **airis-studio**: merge=deploy レーン稼働 (deploy-stg.yml、既存 ARC runner - + nerdctl direct-bake。ホスト常駐物ゼロ)。bump PR / 耐久マージャは撤去済み。 - stg=本番の single-environment 運用。 -- **agiletec**: CF Workers (corporate/dashboard) は main push → wrangler deploy - (ARC) で stg 自動。k3s レーンは廃止済み (agile-server #400 で manifests 全削除、 - bump 機械と bumper App credential も 2026-06-12 に全撤去)。prd は - Cloudflare (frontend promote = 中井手動) + Supabase (migrations / Edge - Functions = main マージで CI 自動 deploy・drift gate 付き、上記 §3 例外)。 -- **Public repos**: release.yml は配布物の公開用として継続 (cmd-ime / - airis-mcp-gateway が参照実装)。 -- **旧 release-driven stg deploy 標準 (plan 520) は superseded** (2026-06-12)。 -- **bump PR 機構は org から完全撤去** (2026-06-12): auto-merge-bumps.yml 削除、 - bump/* ブランチ削除、DEPLOY_BUMPER_* / IMAGE_BUMPER_* org credential 削除、 - agiletec-image-bumper App はアンインストール。 - ## References - [GitHub Actions: events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows) diff --git a/policies/org-quality-gate.md b/policies/org-quality-gate.md index b39fd60..e9874c6 100644 --- a/policies/org-quality-gate.md +++ b/policies/org-quality-gate.md @@ -1,10 +1,7 @@ -# Organization quality gate contract +# Organization quality gate契約 -The organization-required workflow runs the same gate for every repository: stack detection picks -the applicable generic language jobs (Node, Bun, Python, Rust, Swift), and the secret scan, -feature-flag check, and final aggregator always run. +organization required workflowは全repoへ同じgateを適用する。stack detectionがNode、Bun、Python、Rust、Swiftの +該当jobを選び、secret scan、feature flag check、final aggregatorは常に実行する。 -There is no per-repository exception mechanism (owner ruling 2026-07-24). A repository with its own -native CI still runs the generic stack jobs; duplication is accepted in exchange for a single -uniform gate. Do not reintroduce repository-name conditions or opt-out inputs into -`org-quality-gate.yml` / `quality-gate.yml`. +repo別の例外機構は設けない。native CIを持つrepoでもgeneric stack jobを実行し、単一で均一なgateを優先する。 +`org-quality-gate.yml` / `quality-gate.yml`へrepo名条件やopt-out inputを再導入しない。