Skip to content

Commit 98c2cd9

Browse files
haksungjangclaude
haksungjang
and
claude
committed
docs: README·CONTRIBUTING 이중 언어화, STYLEGUIDE 교체
- README.md: 한/영 이중 언어 구조 적용 (Option B) → 언어 전환 앵커 링크, 영어 섹션 전체 번역 추가 - CONTRIBUTING.md: 한/영 이중 언어 구조 적용 → verify.sh 오류 해결법, 참고 문서 등 영어 번역 추가 - STYLEGUIDE.md: React Native 오내용 → trustedoss 전용 스타일 가이드로 교체 → 문서 구조 원칙, 용어 규칙, ISO 번호 체계, front matter 등 한/영 이중 언어 Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
1 parent c55485a commit 98c2cd9

3 files changed

Lines changed: 663 additions & 74 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
[🇰🇷 한국어](#한국어) | [🇺🇸 English](#english)
2+
3+
---
4+
5+
<a id="한국어"></a>
6+
17
# 기여 가이드
28

39
trustedoss에 기여해주셔서 감사합니다.
@@ -137,3 +143,147 @@ FAIL: agent 실행 admonition 누락
137143
| `.claude/scripts/verify.sh` | 검증 항목 전체 소스 |
138144
| `.claude/reference/iso-5230.md` | ISO/IEC 5230 스펙 전문 |
139145
| `.claude/reference/iso-18974.md` | ISO/IEC 18974 스펙 전문 |
146+
147+
---
148+
149+
<a id="english"></a>
150+
151+
# Contributing Guide
152+
153+
Thank you for contributing to trustedoss.
154+
155+
---
156+
157+
## Scope of Work
158+
159+
This project handles **content work only**.
160+
161+
| Allowed (O) | Not Allowed (X) |
162+
| ------------------------------ | ------------------------------------------------- |
163+
| `docs/` | `website/src/` (except CSS exceptions) |
164+
| `agents/` | `website/static/` |
165+
| `templates/` | `website/src/**/*.ts`, `*.tsx` |
166+
| `.claude/` | `*.js`, `*.css`, `*.scss` (except CSS exceptions) |
167+
| `CLAUDE.md` | All configuration files |
168+
| `website/ai-coding/` (md only) | |
169+
| `website/devsecops/` (md only) | |
170+
171+
If design or code changes appear necessary, stop work and open an issue for discussion.
172+
173+
---
174+
175+
## 5 Required Steps Before Push
176+
177+
```
178+
Step 1 /qa changed # Quality check (requires Claude session)
179+
Step 2 bash .claude/scripts/verify.sh # Confirm 11/11 PASS
180+
Step 3 Update .claude/progress.md # Check completed items, update next tasks
181+
Step 4 git add -p && git commit -m "..." # Stage files selectively
182+
Step 5 git push # Only after all checks pass
183+
```
184+
185+
> **Note**: Use `git add -p` instead of `git add -A` or `git add .` to stage files selectively.
186+
> This prevents accidentally committing `.env`, local config files, or unnecessary binaries.
187+
188+
---
189+
190+
## Verification Command Reference
191+
192+
| Command | Role | Time |
193+
| -------------------------------------------- | --------------------------------------- | ------- |
194+
| `/qa changed` | Auto-check and fix changed file quality | ~2 min |
195+
| `bash .claude/scripts/verify.sh` | Run all 11 static validation checks | ~30 sec |
196+
| `python3 .claude/scripts/test-coverage.py` | Verify ISO requirement coverage | ~5 sec |
197+
| `python3 .claude/scripts/validate-output.py` | Verify output/ deliverable completeness | ~5 sec |
198+
| `/kwg-check` | Check sync status with KWG source | ~1 min |
199+
200+
---
201+
202+
## Common verify.sh FAIL Errors
203+
204+
### [1/11] Docusaurus Build Failure
205+
206+
```
207+
FAIL: Docusaurus 빌드 실패
208+
```
209+
210+
**Cause**: Invalid Markdown syntax, broken imports, or front matter YAML errors
211+
**Fix**: Check the build log for the error file and line number → fix the file
212+
213+
---
214+
215+
### [2/11] Broken Internal Links
216+
217+
```
218+
FAIL: 깨진 링크 발견
219+
```
220+
221+
**Cause**: Links not updated after file moves or deletions, or typos
222+
**Fix**: Verify the target file path and correct the relative path
223+
224+
---
225+
226+
### [3/11] Front Matter YAML Error
227+
228+
```
229+
FAIL: front matter YAML 오류
230+
```
231+
232+
**Cause**: Missing or incorrectly indented fields among `작성일:`, `버전:`, `충족 체크리스트:`, `셀프스터디 소요시간:`
233+
**Fix**: Confirm all 4 front matter fields exist in docs/ files
234+
235+
---
236+
237+
### [5/11] Local Path Exposed
238+
239+
```
240+
FAIL: 로컬 사용자 경로 노출
241+
```
242+
243+
**Cause**: Absolute paths containing `/Users/username` or `C:\Users\username`
244+
**Fix**: Replace with relative paths (`./`) or generalized paths (`/path/to/trustedoss`)
245+
246+
---
247+
248+
### [6/11] ISO Section Number Format Error
249+
250+
```
251+
FAIL: 18974 섹션 번호 형식 오류
252+
```
253+
254+
**Cause**: ISO/IEC 18974 section numbers using `3.x.x` (mixing with the 5230 scheme)
255+
**Fix**: ISO/IEC 18974 must always use the `4.x.x` scheme
256+
257+
| Standard | Correct Format | Incorrect Format |
258+
| ------------- | -------------- | ---------------- |
259+
| ISO/IEC 5230 | `3.1.1` | — |
260+
| ISO/IEC 18974 | `4.1.1` | ~~`3.1.1`~~ |
261+
262+
---
263+
264+
### [7/11] Missing Agent Execution Admonition
265+
266+
```
267+
FAIL: agent 실행 admonition 누락
268+
```
269+
270+
**Cause**: No session-exit admonition immediately before a `cd agents/...` bash code block
271+
**Fix**: Add the following admonition directly above the code block:
272+
273+
```
274+
:::tip Before Running
275+
First exit the current Claude session (`/exit` or `Ctrl+C`), then run the command below in a new terminal.
276+
:::
277+
```
278+
279+
---
280+
281+
## Reference Documents
282+
283+
| Document | Content |
284+
| -------------------------------- | --------------------------------------- |
285+
| `CLAUDE.md` | Scope, path rules, skills & agent list |
286+
| `.claude/harness-guide.md` | QA harness slash command detailed usage |
287+
| `.claude/scripts/verify.sh` | Full source for all validation checks |
288+
| `.claude/reference/iso-5230.md` | ISO/IEC 5230 full specification |
289+
| `.claude/reference/iso-18974.md` | ISO/IEC 18974 full specification |

‎README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,12 @@
22
[![OpenChain](https://img.shields.io/badge/OpenChain-ISO%2FIEC%205230%20%26%2018974-blue)](https://www.openchainproject.org/conformance)
33
[![Site](https://img.shields.io/badge/Site-trustedoss.github.io-green)](https://trustedoss.github.io)
44

5+
[🇰🇷 한국어](#한국어) | [🇺🇸 English](#english)
6+
7+
---
8+
9+
<a id="한국어"></a>
10+
511
# Trusted OSS
612

713
**신뢰할 수 있는 오픈소스 공급망 관리** — ISO/IEC 5230 & 18974 실전 키트 + AI 코딩·DevSecOps 자동화 가이드
@@ -181,3 +187,187 @@ OpenChain KWG 커뮤니티와 연계하여 운영됩니다. PR과 이슈 제출
181187
## 라이선스
182188

183189
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
190+
191+
---
192+
193+
<a id="english"></a>
194+
195+
# Trusted OSS — English
196+
197+
**Trusted Open Source Supply Chain Management** — ISO/IEC 5230 & 18974 Practical Kit + AI Coding & DevSecOps Automation Guide
198+
199+
Even those with no prior open source management experience can complete ISO/IEC 5230 and ISO/IEC 18974 self-certification declarations by following this kit. Agents automatically generate deliverables tailored to your organization, and the kit is designed for self-study.
200+
201+
The web guide and browser-based tools are available at **[trustedoss.github.io/en](https://trustedoss.github.io/en)**.
202+
203+
---
204+
205+
## What We Offer
206+
207+
| Section | Content |
208+
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
209+
| [Build Your System](https://trustedoss.github.io/en/docs) | Step-by-step guide to building an open source governance system based on ISO/IEC 5230 & 18974 |
210+
| [AI Coding](https://trustedoss.github.io/en/ai-coding/intro) | Automated open source policy compliance for AI coding tools like Claude Code, Cursor, and Copilot |
211+
| [DevSecOps](https://trustedoss.github.io/en/devsecops/intro) | CI/CD pipeline automation for SAST, SCA, secret detection, container, IaC, and DAST |
212+
| [Reference](https://trustedoss.github.io/en/reference/intro) | Policy templates, SBOM samples, and self-certification checklists |
213+
214+
---
215+
216+
## Quick Start
217+
218+
### Use in the Browser (No Claude Code Required)
219+
220+
Browser-based tools are available with just an Anthropic API key.
221+
222+
| Tool | Description | Location |
223+
| ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
224+
| Rules Generator | Auto-generate open source policy files for AI coding tools | [AI Coding → Rules Template](https://trustedoss.github.io/en/ai-coding/rules-template) |
225+
| Workflow Generator | Auto-generate DevSecOps CI/CD pipeline YAML | [AI Coding → Quick CI/CD](https://trustedoss.github.io/en/ai-coding/cicd-quick) |
226+
| SBOM Analyzer | Upload SBOM file → vulnerability response report | [DevSecOps → SCA](https://trustedoss.github.io/en/devsecops/sca) |
227+
| SAST Analyzer | Semgrep/CodeQL results → fix guide | [DevSecOps → SAST](https://trustedoss.github.io/en/devsecops/sast) |
228+
| Secret Analyzer | Gitleaks results → immediate response procedure | [DevSecOps → Secret Detection](https://trustedoss.github.io/en/devsecops/secret-detection) |
229+
| IaC Fixer | Checkov results → auto-generate fix code | [DevSecOps → IaC Security](https://trustedoss.github.io/en/devsecops/iac-security) |
230+
231+
### Run with Claude Code
232+
233+
```bash
234+
# 1. Clone the repository
235+
git clone https://github.com/trustedoss/trustedoss.github.io.git
236+
237+
# 2. Enter the project and launch Claude Code
238+
cd trustedoss.github.io && claude
239+
240+
# 3. Ask for guidance (type in Korean)
241+
# "어디서 시작해야 해?" (meaning: "Where should I start?")
242+
```
243+
244+
---
245+
246+
## Agent List
247+
248+
### Compliance Agents (ISO/IEC 5230 & 18974)
249+
250+
| Agent | Role | How to Run |
251+
| --------------------------------- | ----------------------------------------- | ---------------------------------------------- |
252+
| `agents/02-organization-designer` | Generate organization & role deliverables | `cd agents/02-organization-designer && claude` |
253+
| `agents/03-policy-generator` | Generate open source policy document | `cd agents/03-policy-generator && claude` |
254+
| `agents/04-process-designer` | Generate process documents & flowcharts | `cd agents/04-process-designer && claude` |
255+
| `agents/05-sbom-guide` | Generate SBOM commands & scripts | `cd agents/05-sbom-guide && claude` |
256+
| `agents/05-sbom-analyst` | Generate SBOM license analysis report | `cd agents/05-sbom-analyst && claude` |
257+
| `agents/05-sbom-management` | Generate SBOM management plan & templates | `cd agents/05-sbom-management && claude` |
258+
| `agents/05-vulnerability-analyst` | Generate vulnerability analysis report | `cd agents/05-vulnerability-analyst && claude` |
259+
| `agents/06-training-manager` | Generate training curriculum & tracking | `cd agents/06-training-manager && claude` |
260+
| `agents/07-conformance-preparer` | Generate gap analysis & declaration draft | `cd agents/07-conformance-preparer && claude` |
261+
262+
### AI Coding & DevSecOps Agents (Level 1 — Config Generation)
263+
264+
| Agent | Role | How to Run |
265+
| ------------------------ | ------------------------------------------------- | ------------------------------------- |
266+
| `agents/ai-coding-setup` | Analyze project and generate custom Rules files | `cd agents/ai-coding-setup && claude` |
267+
| `agents/devsecops-setup` | Analyze project and generate CI/CD pipeline files | `cd agents/devsecops-setup && claude` |
268+
269+
### AI Coding & DevSecOps Agents (Level 1 — Result Analysis)
270+
271+
| Agent | Role | How to Run |
272+
| -------------------------- | -------------------------------------------- | --------------------------------------- |
273+
| `agents/sbom-vuln-analyst` | SBOM/grype results → vulnerability report | `cd agents/sbom-vuln-analyst && claude` |
274+
| `agents/sast-analyst` | Semgrep/CodeQL results → fix guide | `cd agents/sast-analyst && claude` |
275+
| `agents/secret-analyst` | Gitleaks results → secret response procedure | `cd agents/secret-analyst && claude` |
276+
| `agents/iac-fixer` | Checkov results → auto-generate IaC fix code | `cd agents/iac-fixer && claude` |
277+
278+
### CI/CD Automation Agents (Level 2)
279+
280+
| Agent | Role | How to Run |
281+
| ---------------------------------------- | --------------------------------------------------- | ----------------------------------------------------- |
282+
| `agents/level2-automation/pr-comment` | Generate PR security analysis auto-comment workflow | `cd agents/level2-automation/pr-comment && claude` |
283+
| `agents/level2-automation/issue-tracker` | Generate scheduled scan issue auto-filing workflow | `cd agents/level2-automation/issue-tracker && claude` |
284+
285+
---
286+
287+
## Repository Structure
288+
289+
```
290+
trustedoss/
291+
├── docs/ # Chapter-by-chapter guide documents
292+
├── agents/ # Deliverable auto-generation agents
293+
│ ├── 02-organization-designer/
294+
│ ├── 03-policy-generator/
295+
│ ├── ...
296+
│ ├── ai-coding-setup/ # AI coding Rules file generation
297+
│ ├── devsecops-setup/ # DevSecOps pipeline file generation
298+
│ ├── sbom-vuln-analyst/ # SBOM vulnerability analysis
299+
│ ├── sast-analyst/ # SAST result analysis
300+
│ ├── secret-analyst/ # Secret detection result analysis
301+
│ ├── iac-fixer/ # IaC fix code generation
302+
│ └── level2-automation/ # CI/CD integration automation
303+
├── templates/ # Document templates
304+
├── samples/ # Sample projects for practice
305+
├── output/ # Generated deliverables (.gitignore)
306+
├── .claude/ # Claude Code configuration & skills
307+
└── website/ # Documentation website source (Docusaurus)
308+
```
309+
310+
---
311+
312+
## Chapter List
313+
314+
| Chapter | Content | Self-study |
315+
| ------------------------ | ---------------------------------------------- | ---------- |
316+
| 00-overview | Overview of both standards & checklist mapping | 1 hour |
317+
| 00-overview/supply-chain | Software supply chain security + SBOM concepts | 1 hour |
318+
| 01-setup | Environment setup (Docker, Git, Claude Code) | 30 min |
319+
| 02-organization | Organizational structure & role assignment | 1 hour |
320+
| 03-policy | Open source policy establishment | 1 hour |
321+
| 04-process | Open source process design | 1 hour |
322+
| 05-tools/sbom-generation | SBOM generation | 1 hour |
323+
| 05-tools/sbom-management | SBOM management & sharing | 1 hour |
324+
| 05-tools/vulnerability | Vulnerability analysis & response | 1 hour |
325+
| 06-training | Training program setup | 30 min |
326+
| 07-conformance | Self-certification declaration | 30 min |
327+
328+
---
329+
330+
## Deliverables
331+
332+
| File | Description | Standard |
333+
| --------------------------------------------- | ------------------------------------------- | ------------ |
334+
| `output/organization/role-definition.md` | Open source program manager role definition | 5230 + 18974 |
335+
| `output/organization/raci-matrix.md` | RACI responsibility matrix | 5230 + 18974 |
336+
| `output/organization/appointment-template.md` | Role appointment letter template | 5230 + 18974 |
337+
| `output/policy/oss-policy.md` | Open source policy document | 5230 + 18974 |
338+
| `output/policy/license-allowlist.md` | Approved license list | 5230 |
339+
| `output/process/usage-approval.md` | Open source usage approval procedure | 5230 |
340+
| `output/process/distribution-checklist.md` | Pre-distribution checklist | 5230 |
341+
| `output/process/vulnerability-response.md` | Vulnerability response procedure | 18974 |
342+
| `output/process/process-diagram.md` | End-to-end process diagram | 5230 + 18974 |
343+
| `output/sbom/[project].cdx.json` | SBOM (CycloneDX format) | 5230 + 18974 |
344+
| `output/sbom/license-report.md` | License analysis report | 5230 |
345+
| `output/sbom/copyleft-risk.md` | Copyleft risk analysis | 5230 |
346+
| `output/sbom/sbom-management-plan.md` | SBOM management plan | 18974 |
347+
| `output/vulnerability/cve-report.md` | CVE vulnerability analysis report | 18974 |
348+
| `output/vulnerability/remediation-plan.md` | Vulnerability remediation plan | 18974 |
349+
| `output/training/curriculum.md` | Training curriculum | 5230 + 18974 |
350+
| `output/conformance/gap-analysis.md` | Gap analysis report | 5230 + 18974 |
351+
| `output/conformance/declaration-draft.md` | Self-certification declaration draft | 5230 + 18974 |
352+
353+
---
354+
355+
## Links
356+
357+
- [Trusted OSS Website](https://trustedoss.github.io/en)
358+
- [OpenChain KWG](https://openchain-project.github.io/OpenChain-KWG/)
359+
- [ISO/IEC 5230](https://www.iso.org/standard/81039.html)
360+
- [ISO/IEC 18974](https://www.iso.org/standard/86450.html)
361+
- [OpenChain Self-Certification Registration](https://www.openchainproject.org/conformance)
362+
363+
---
364+
365+
## Contributing
366+
367+
This project is operated in collaboration with the OpenChain KWG community. Pull requests and issues are welcome.
368+
369+
---
370+
371+
## License
372+
373+
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)

0 commit comments

Comments
 (0)