[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"markdown-content-contribution":3},"# 贡献指南\n\n感谢您对 Open Security Information Model (OSIM) 项目的关注！我们热烈欢迎社区成员参与贡献，共同推动安全数据标准化的发展。\n\n## 贡献者行为准则\n\n参与本项目即表示您同意遵守我们的 [行为准则](CODE_OF_CONDUCT.md)。请在您与项目的所有互动中遵循它。\n\n## 开始贡献\n\n### 前置要求\n\n- 基本的 Git 和 GitHub 使用知识\n- 了解 JSON 格式\n- 熟悉网络安全基础概念（针对 Schema 贡献）\n\n### 首次贡献\n\n如果您是首次贡献者，我们推荐从以下类型的任务开始：\n\n- 文档改进和错别字修正\n- 现有 Schema 描述的优化\n- 为字段添加更清晰的描述或示例\n- 报告明确的 Schema 定义问题\n\n您可以在 Issue 列表中寻找标有 `good first issue` 或 `help wanted` 的标签。\n\n## 贡献流程\n\n### 1. 报告问题\n\n#### 创建 Issue\n在创建新 Issue 前，请：\n- 检查 [Issue 列表](https://github.com/osim-group/osim-schema/issues) 是否已有类似问题\n- 使用清晰的标题和描述\n- 对于 Schema 问题，提供具体的 Schema 名称和字段名称\n- 描述期望的行为或改进建议\n\n#### Issue 模板\n我们提供以下 Issue 模板：\n- **Schema 问题**: 用于报告 Schema 定义中的问题\n- **文档改进**: 用于文档相关的改进建议\n- **功能请求**: 用于建议新的 Schema 或字段\n- **问题咨询**: 用于技术咨询和讨论\n\n### 2. 开发环境设置\n\n#### Fork 和克隆仓库\n```bash\n# Fork 本仓库到您的 GitHub 账户\n# 克隆您的 fork\ngit clone https://github.com/您的用户名/osim-schema.git\ncd osim-schema\n\n# 添加上游仓库\ngit remote add upstream https://github.com/osim-group/osim-schema.git\n```\n\n### 3. 创建分支\n\n我们使用特性分支工作流：\n```bash\n# 从 main 分支创建新分支\ngit checkout -b schema/简短描述\n# 或者修复问题\ngit checkout -b fix/问题描述\n```\n\n分支命名约定：\n- `schema/`: 新增或修改 Schema\n- `docs/`: 文档改进\n- `fix/`: 问题修复\n- `enhancement/`: 现有 Schema 的优化\n\n### 4. 进行修改\n\n#### Schema 开发指南\n\n**新增 Schema**\n1. 确定适当的 `group` 和 `category`（参考现有 Schema 的分类）\n2. 创建新的 JSON 文件\n3. 遵循以下结构格式：\n```json\n{\n  \"group\": \"log\",\n  \"category\": \"category_name\",\n  \"title\": \"schema_name\",\n  \"label\": \"Human Readable Label\",\n  \"description\": \"Detailed description of this schema's purpose and usage scenarios.\",\n  \"tag\": [\"relevant\", \"tags\"],\n  \"dataSource\": [\"Data Source 1\", \"Data Source 2\"],\n  \"definitions\": {\n    \"fieldName\": {\n      \"label\": \"Field Label\",\n      \"requirement\": \"REQUIRED/OPTIONAL/RECOMMENDED\",\n      \"description\": \"Detailed description of the field, including its purpose and usage.\",\n      \"type\": \"string/integer/long/boolean/array/enum\",\n      \"valid_type\": \"string_t/integer_t/boolean_t/array_t\",\n      \"dataSource\": [\"Optional data source information\"],\n      \"enum\": {\n          \"enumValue\": {\n              \"label\": \"Enum Label\",\n              \"description\": \"Detailed description of the value\"\n          }\n      }\n    }\n  }\n}\n```\n\n**修改现有 Schema**\n\n1. 保持向后兼容性，避免删除或重命名现有字段\n2. 如果需要添加新字段，确保它们有清晰的描述\n3. 更新字段的 `requirement` 属性时要谨慎\n\n**字段定义规范**\n\n- `requirement`: 必须为 \"REQUIRED\"、\"OPTIONAL\" 或 \"RECOMMENDED\"\n- `type`: 基本的数据类型\n- `valid_type`: 更具体的验证类型（参考现有 Schema 的用法），详情可见[valid.json](https://github.com/osim-group/osim-schema/blob/main/valid.json)\n- `description`: 必须清晰说明字段的用途和预期值\n\n**分类指南**\n- **group**: 高层次分组（如 log, alert, incident等）\n- **category**: 更具体的分类（如 authentication_and_access, network_security 等）\n- **tag**: 用于搜索和过滤的关键词\n- **dataSource**: 此 Schema 适用的数据源类型\n\n#### 文档贡献\n- 确保所有字段都有完整的中文或英文描述\n- 更新 README.md 中的分类说明\n- 添加 Schema 使用的最佳实践指南\n- 维护数据字典和术语表\n\n### 5. 提交更改\n\n#### 提交消息规范\n我们采用约定式提交：\n```\n\u003C类型>[可选的作用域]: \u003C描述>\n\n[可选的正文]\n\n[可选的脚注]\n```\n\n类型包括：\n- `feat`: 新增 Schema 或字段\n- `fix`: Schema 问题修复\n- `docs`: 文档更新\n- `enhance`: 现有 Schema 的优化\n- `refactor`: Schema 结构调整\n- `other`: 其他更新内容\n\n示例：\n```bash\ngit commit -m \"feat(authentication): 新增应用访问认证 Schema\n\n- 新增 application_access_authentication.json\n- 包含 machineCode 等必需字段\n- 添加相关标签和数据源\n- 提供详细的字段描述\n\nCloses #123\"\n```\n\n### 6. 推送和创建 Pull Request\n\n```bash\n# 推送到您的 fork\ngit push origin schema/您的功能名称\n```\n\n然后在 GitHub 上创建 Pull Request：\n\n#### PR 模板要求\n每个 PR 应该包含：\n- **清晰的标题**: 描述修改内容\n- **详细描述**: 说明修改的原因、内容和影响\n- **相关 Issue**: 链接到相关的 Issue\n- **验证说明**: 描述如何验证这些修改\n- **检查清单**: 确保完成所有必要步骤\n\n#### PR 检查清单\n在创建 PR 前，请确认：\n- [ ] Schema 格式正确，符合 JSON 规范\n- [ ] 字段描述清晰完整\n- [ ] 使用了正确的分类和标签\n- [ ] 更新了相关文档（如需要）\n- [ ] 提交信息符合规范\n- [ ] 分支与最新 main 分支同步\n\n## 贡献领域\n\n### Schema 设计贡献\n- 新增Schema类型\n- 添加新的字段定义\n- 优化现有字段描述\n- 扩展数据源支持\n\n### 分类体系贡献\n- 建议新的 group 或 category\n- 改进标签系统\n- 建立 Schema 间的关系\n\n### 文档贡献\n- 完善字段描述和示例\n- 编写使用指南和最佳实践\n- 创建 Schema 关系图\n- 翻译文档内容\n\n### 社区贡献\n- 回答问题，帮助其他用户\n- 评审其他人的 PR\n- 分享实施经验\n- 参与社区讨论\n\n## 审查流程\n\n1. **格式检查**: 验证 JSON 格式正确性\n2. **内容审查**: 至少需要一名维护者审查 Schema 内容\n3. **一致性检查**: 确保与现有 Schema 保持一致性\n4. **修改请求**: 如有需要，贡献者根据反馈进行修改\n5. **合并**: 审查通过后由维护者合并\n\n### 审查重点\n- Schema 结构的完整性和正确性\n- 字段描述的清晰度和准确性\n- 分类和标签的合理性\n- 与现有 Schema 的一致性\n- 向后兼容性考虑\n\n## 社区角色\n\n### 贡献者\n所有提交过 PR 的社区成员都是贡献者。\n\n### 维护者\n活跃的贡献者可能被邀请成为维护者，职责包括：\n- Schema 审查和合并\n- Issue 分类和响应\n- 项目发展规划\n- 版本发布管理\n\n## 获取帮助\n\n- **技术问题**: 在 GitHub Discussions 中提问\n- **Schema 设计咨询**: 在 Issue 中讨论\n- **文档**: 查看项目文档\n\n## 版本发布\n\n项目采用语义化版本控制：\n- **主版本 (X.0.0)**: 不兼容的 Schema 修改\n- **次版本 (0.X.0)**: 向后兼容的功能新增\n- **修订号 (0.0.X)**: 向后兼容的问题修正\n\n发布流程：\n1. Schema 冻结和社区审查\n2. 版本号确定和更新\n3. 正式版本发布\n4. 发布公告\n\n## 知识产权\n\n- 所有贡献必须遵循项目的开源协议\n- 贡献者保留其内容的版权，但同意在项目协议下授权使用\n- 确保您的贡献不侵犯第三方知识产权\n\n## 致谢\n\n所有贡献者都将被列入项目的致谢列表。重大的贡献可能会获得维护者提名。\n\n---\n\n再次感谢您的贡献！您的参与让开源社区更加美好。\n\n如有任何问题，请随时在 Issue 中提出或通过讨论区联系我们。\n\nHappy Contributing! 🎉\n",1775524373151]