[docs] add GitHub Discussions templates for announcements and project introduction

- Added `DISCUSSION_TEMPLATE.md` for GitHub Discussions announcements. - Introduced `DISCUSSION_001_PROJECT_INTRODUCTION.md` as a draft for the project introduction, architecture, and roadmap. - Templates provide bilingual (Korean/English) guidance for consistency and accessibility.
2025-12-07 20:35:44 +09:00 · 2025-11-27 15:48:03 +09:00
parent f110c33d4d
commit 5388517767
2 changed files with 249 additions and 0 deletions
--- a/.github/DISCUSSION_001_PROJECT_INTRODUCTION.md
+++ b/.github/DISCUSSION_001_PROJECT_INTRODUCTION.md
@@ -0,0 +1,130 @@
+# HopGate: Project Introduction, Architecture & Roadmap / HopGate: 프로젝트 소개, 아키텍처, 로드맵
+
+<!--
+This document is intended to be posted as GitHub Discussions #1 (Announcement).
+Copy & paste it into a new Discussion under the "Announcements" category and edit as needed.
+
+이 문서는 GitHub Discussions의 #1 공지(Announcement)로 게시하기 위한 초안입니다.
+"Announcements" 카테고리의 새 Discussion에 복사해 붙여 넣은 뒤 필요에 맞게 수정해서 사용하세요.
+-->
+
+## 1. What is HopGate? / HopGate란?
+
+HopGate is a gateway that provides a **DTLS-based HTTP(S) tunnel** between a public server and multiple clients in private networks.
+HopGate는 공인 서버와 여러 프라이빗 네트워크 클라이언트 사이에 **DTLS 기반 HTTP(S) 터널**을 제공하는 게이트웨이입니다.
+
+Key characteristics / 주요 특징:
+
+- The server listens on ports **80/443** and automatically issues/renews TLS certificates via **ACME** (e.g. Let's Encrypt).
+- 서버는 **80/443 포트**를 점유하고 **ACME**(예: Let's Encrypt)를 통해 TLS 인증서를 자동 발급/갱신합니다.
+- Transport between server and clients uses **DTLS**, tunneling HTTP request/response messages.
+- 서버–클라이언트 간 전송은 **DTLS** 위에서 이루어지며 HTTP 요청/응답을 메시지로 터널링합니다.
+- An **admin management plane (REST API)** handles domain registration/unregistration and client API key issuance.
+- **관리 Plane(REST API)** 를 통해 도메인 등록/해제와 클라이언트 API Key 발급을 수행합니다.
+- Logs are JSON-structured and designed to work well with **Prometheus + Loki + Grafana**.
+- 로그는 JSON 구조로 출력되며 **Prometheus + Loki + Grafana** 스택과 잘 연동되도록 설계되었습니다.
+
+For more details, see the architecture document in the repository. / 더 자세한 내용은 저장소의 아키텍처 문서를 참고해주세요.
+
+- [`ARCHITECTURE.md`](../ARCHITECTURE.md)
+- [`README.md`](../README.md)
+
+## 2. Project goals & non-goals / 프로젝트 목표와 비목표
+
+### Goals / 목표
+
+- Provide a simple, self-hostable DTLS-based HTTP(S) tunneling gateway.
+- 단순하고 셀프 호스트 가능한 DTLS 기반 HTTP(S) 터널링 게이트웨이를 제공합니다.
+- Make it easy to expose services running in private networks securely to the public Internet.
+- 프라이빗 네트워크 내부의 서비스를 안전하게 퍼블릭 인터넷에 노출할 수 있도록 돕습니다.
+- Offer clear observability hooks (metrics, logs) for production operations.
+- 프로덕션 운영을 위한 메트릭·로그 등 가시성(Observability)을 명확히 제공합니다.
+
+### Non-goals (for now) / 현재 범위 밖(Non-goals)
+
+- Being a full replacement for all kinds of VPN solutions.
+- 모든 종류의 VPN 솔루션을 완전히 대체하는 것을 목표로 하지 않습니다.
+- Providing a multi-protocol tunneling solution beyond HTTP(S).
+- HTTP(S) 이외의 멀티 프로토콜 터널링 솔루션을 지향하지 않습니다.
+
+These may evolve over time as the project matures. / 프로젝트 성숙도에 따라 이 범위는 향후 달라질 수 있습니다.
+
+## 3. Architecture overview / 아키텍처 개요
+
+At a high level, HopGate consists of the following components. / 높은 수준에서 HopGate는 다음과 같은 컴포넌트로 구성됩니다.
+
+- **Public server / 공인 서버**: Terminates TLS, manages ACME, accepts DTLS connections, forwards HTTP(S) traffic.
+- **공인 서버**: TLS 종단, ACME 인증서 관리, DTLS 연결 수립, HTTP(S) 트래픽 포워딩을 담당합니다.
+- **Clients / 클라이언트**: Run inside private networks, connect to the server via DTLS, proxy HTTP requests to local services (127.0.0.1:PORT).
+- **클라이언트**: 프라이빗 네트워크 내부에서 동작하며 DTLS로 서버에 연결하고, 서버가 전달한 HTTP 요청을 로컬 서비스(127.0.0.1:PORT)에 대신 보내고 응답을 다시 서버로 전달합니다.
+- **Admin API / 관리 API**: REST endpoints for managing domains, API keys, and possibly future admin operations.
+- **관리 API**: 도메인, API Key 및 향후 추가될 관리자 기능을 위한 REST 엔드포인트를 제공합니다.
+- **Observability stack / 가시성 스택**: Metrics and logs intended to be scraped/collected by Prometheus, Loki, Grafana, etc.
+- **가시성 스택**: 메트릭과 로그는 Prometheus, Loki, Grafana 등에서 수집·시각화하기 쉽도록 설계되어 있습니다.
+
+For a more detailed diagram and explanation, refer to the architecture document. / 더 상세한 다이어그램과 설명은 아키텍처 문서를 참고해주세요.
+
+- [`ARCHITECTURE.md`](../ARCHITECTURE.md)
+
+## 4. Tech stack & languages / 기술 스택과 언어
+
+- Implementation language: **Go**
+- 구현 언어: **Go**
+- Transport: **DTLS** over UDP
+- 전송 계층: UDP 위의 **DTLS**
+- Certificate management: **ACME** (e.g. Let's Encrypt)
+- 인증서 관리: **ACME** (예: Let's Encrypt)
+- Data store (planned for production): **PostgreSQL + ent**
+- 데이터 저장소(프로덕션 계획): **PostgreSQL + ent**
+- Observability: **Prometheus, Loki, Grafana-friendly logs and metrics**
+- 가시성: **Prometheus, Loki, Grafana 친화적인 로그 및 메트릭**
+
+Documentation and communication policy / 문서 및 커뮤니케이션 원칙:
+
+- We aim for **Korean / English bilingual** docs where possible. / 가능하면 문서는 **한국어/영어 병기**를 지향합니다.
+- Code comments and commit messages may be in English, but user-facing docs are typically ko/en. / 코드 주석과 커밋 메시지는 주로 영어를 사용하되, 사용자 대상 문서는 ko/en 병기를 유지하려고 합니다.
+
+## 5. Project status & roadmap / 프로젝트 상태와 로드맵
+
+HopGate is currently in an **experimental** stage; APIs and behavior may change at any time.
+HopGate는 아직 **실험 단계(experimental)** 에 있으며, API 및 동작은 언제든지 변경될 수 있습니다.
+
+High-level roadmap (subject to change) / 향후 로드맵(변경 가능):
+
+- Stabilize the core DTLS tunnel and HTTP proxy behavior. / DTLS 터널과 HTTP 프록시 동작을 안정화합니다.
+- Finalize the admin API and domain management flows. / 관리 API와 도메인 관리 플로우를 정리합니다.
+- Wire up PostgreSQL + ent-based domain validation for production. / 프로덕션 환경을 위한 PostgreSQL + ent 기반 도메인 검증을 연동합니다.
+- Harden security defaults and operational practices. / 보안 기본값과 운영 관행을 강화합니다.
+- Improve observability (metrics, logs, dashboards). / 메트릭·로그·대시보드를 포함한 가시성을 개선합니다.
+
+We track progress and milestones in a separate document. / 진행 현황과 마일스톤은 별도 문서로 관리합니다.
+
+- [`progress.md`](../progress.md)
+
+## 6. How to participate / 어떻게 참여할 수 있나요?
+
+We welcome contributions from the community. / 커뮤니티의 다양한 기여를 환영합니다.
+
+- **Issues**
+  - Bug reports, feature requests, design discussions.
+  - 버그 리포트, 기능 제안, 설계 관련 토론을 이슈에 남겨주세요.
+- **Pull Requests**
+  - Implementation of features, bug fixes, docs, refactoring, etc.
+  - 기능 구현, 버그 수정, 문서 개선, 리팩터링 등은 PR로 보내주세요.
+- **Discussions**
+  - Q&A, open-ended ideas, RFC-style proposals.
+  - Q&A, 아이디어 제안, RFC 스타일 제안을 Discussion에서 자유롭게 이야기해주세요.
+
+For commit messages and code style, please refer to the commit message guideline in the repository. / 커밋 메시지와 코드 스타일은 저장소의 커밋 메시지 가이드를 참고해주세요.
+
+- [`COMMIT_MESSAGE.md`](../COMMIT_MESSAGE.md)
+
+## 7. Language policy / 언어 정책
+
+- We use **English as the primary language** for code and interfaces, with **Korean/English bilingual documentation** where reasonable.
+- 코드는 주로 **영어**를 사용하며, 문서는 가능한 범위에서 **한국어/영어 병기**를 유지합니다.
+- Feel free to open Issues or Discussions in either Korean or English. / 이슈나 디스커션은 한국어 또는 영어 중 편한 언어로 작성해도 됩니다.
+
+Thank you for your interest in HopGate. / HopGate에 관심을 가져주셔서 감사합니다.
+
+We look forward to building this project together with the community. / 커뮤니티와 함께 이 프로젝트를 만들어 나가길 기대합니다.
--- a/.github/DISCUSSION_TEMPLATE.md
+++ b/.github/DISCUSSION_TEMPLATE.md
@@ -0,0 +1,119 @@
+# GitHub Discussions Announcement Template / GitHub Discussions 공지 템플릿
+
+<!--
+Use this template when creating an Announcement in GitHub Discussions.
+Copy-paste and edit the content as needed.
+GitHub currently does not support repository-based Discussion templates in .github.
+GitHub Discussions에서 Announcement를 작성할 때 사용하는 템플릿입니다.
+아래 내용을 복사해서 저장소의 Announcement에 붙여넣은 뒤 수정해서 사용하세요.
+현재 .github 디렉터리를 통한 Discussion 템플릿 연동은 지원되지 않습니다.
+-->
+
+## Metadata / 메타데이터
+
+- **Category / 카테고리**: `Announcements`
+- **Status / 상태**: `Planned`, `In progress`, `Completed` (choose one) / (택1)
+- **Related Issue(s) / 관련 이슈**: #ISSUE_ID
+- **Related PR(s) / 관련 PR**: #PR_ID
+- **Target version / 대상 버전**: e.g. `v0.2.0`
+
+---
+
+## Title / 제목
+
+<!-- Short, user-facing title / 사용자 입장에서 이해하기 쉬운 짧은 제목 -->
+
+<!--
+EN: e.g. "Deprecation of legacy ACME endpoint"
+KO: 예) "기존 ACME 엔드포인트 지원 종료 안내"
+-->
+
+## Summary / 개요
+
+<!--
+EN: 2–3 sentences describing what is changing and why it matters.
+KO: 무엇이, 왜 변경되는지 2–3문장으로 요약해주세요.
+-->
+
+- What is changing? / 무엇이 변경되나요?
+- Why are we changing it now? / 왜 지금 변경하나요?
+- Who is affected? / 누가 영향을 받나요?
+
+## Details / 상세 내용
+
+### Motivation / 배경 및 목적
+
+<!--
+EN: Explain the background, problem, or motivation.
+KO: 이 변경의 배경, 문제 의식, 목표를 설명해주세요.
+-->
+
+### What is changing / 변경 사항
+
+<!--
+EN: Describe the technical or behavioral changes in more detail.
+KO: 기술적/동작 측면에서 어떤 변화가 있는지 자세히 적어주세요.
+-->
+
+- [ ] Behavior change / 동작 변화
+- [ ] Configuration change / 설정 변경
+- [ ] API change / API 변경
+- [ ] Operational change (deployment, monitoring, etc.) / 운영 변경(배포, 모니터링 등)
+
+### Timeline / 일정
+
+<!--
+EN: Include key dates (announcement, rollout, deprecation, removal).
+KO: 공지, 롤아웃, 사용 중단, 제거 예정일 등 주요 일정을 적어주세요.
+-->
+
+- Announcement date / 공지 일자: `YYYY-MM-DD`
+- Rollout start / 롤아웃 시작: `YYYY-MM-DD`
+- Deprecation date / 사용 중단 예정: `YYYY-MM-DD`
+- Removal date (if any) / 완전 제거 예정일(선택): `YYYY-MM-DD`
+
+## Impact & Risks / 영향 및 리스크
+
+<!--
+EN: Describe who is affected, possible regressions, and risk level.
+KO: 어떤 사용자가 영향을 받는지, 회귀 가능성과 리스크 수준을 설명해주세요.
+-->
+
+- Affected components / 영향을 받는 컴포넌트:
+- Affected users / 영향을 받는 사용자 그룹:
+- Risk level / 리스크 수준: `Low`, `Medium`, `High`
+
+## Migration / Action items / 마이그레이션 및 필요한 조치
+
+<!--
+EN: Provide clear step-by-step instructions for users.
+KO: 사용자가 따라 할 수 있는 단계별 가이드를 작성해주세요.
+-->
+
+1. Step 1 / 1단계
+2. Step 2 / 2단계
+3. Step 3 / 3단계
+
+## How to give feedback / 피드백 방법
+
+<!--
+EN: Tell users where and how to give feedback (issue, discussion, etc.).
+KO: 피드백을 어디에, 어떻게 남기면 되는지 안내해주세요.
+-->
+
+- Open an Issue: link / 이슈 생성 링크
+- Comment under this Announcement / 이 공지에 댓글로 남기기
+- Other channels (if any) / 기타 채널(있는 경우)
+
+## FAQ (optional) / 자주 묻는 질문 (선택)
+
+<!--
+EN: Add Q&A entries here as they appear.
+KO: 자주 나오는 질문과 답변을 여기에 모아주세요.
+-->
+
+- **Q:**  
+  **A:**
+
+- **Q:**  
+  **A:**