From 7aa22dfaa66d4ec9a8535c598426f688d3595336 Mon Sep 17 00:00:00 2001 From: shalousun <836575280@qq.com> Date: Wed, 18 Oct 2023 19:10:57 +0800 Subject: [PATCH 1/2] add: update contributing --- docs/zh-cn/_sidebar.md | 4 +- docs/zh-cn/community/contributing.md | 86 ++++++++++++++++++---------- docs/zh-cn/community/developer.md | 66 +++++++++++++++++++++ 3 files changed, 125 insertions(+), 31 deletions(-) create mode 100644 docs/zh-cn/community/developer.md diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index cc8bef4..529d763 100644 --- a/docs/zh-cn/_sidebar.md +++ b/docs/zh-cn/_sidebar.md @@ -27,5 +27,5 @@ - [扩展开发](zh-cn/expand.md) - [变更日志](zh-cn/changelog.md) - 社区 - - [团队](zh-cn/community/team.md) - - [开源贡献](zh-cn/community/contributing.md) \ No newline at end of file + - [贡献指南](zh-cn/community/contributing.md) + - [开发者](zh-cn/community/developer.md) diff --git a/docs/zh-cn/community/contributing.md b/docs/zh-cn/community/contributing.md index 9b875ef..8a15215 100644 --- a/docs/zh-cn/community/contributing.md +++ b/docs/zh-cn/community/contributing.md @@ -1,29 +1,57 @@ -smart-doc贡献指南 -# 我们为什么应该参与开源 -作为smart-doc的作者，结合我个人的经验告诉你，我给大家总结几点为什么你应该参与一些项目的开源。 - -- 参与开源可以提升个人成就感，尤其是你参与一个很多人使用开源项目，你为社会贡献了自己价值。 -- 在大厂就职过的很多人都知道，大厂里技术升职级的时候有一个指标是个人技术影响力，对重视技术的公司，这个指标非常重要， -这个技术影响力的来源主要就三种：主导或参与主流开源项目；在国内的知名社区或者是比较知名的技术公众号发表过有一定深度的技术文档；另外一个是写书出版。 -写书就比较复杂，这涉及构思正本书的内容框架。 -- 提升个人简历，我个人也曾在国内某知名公司工作时面试过不少人，包括参与过简历筛选。对大厂来说，在小公司工作写过的一堆项目放在简历上， -基本没有什么用，尤其是各种管理系统都不如你把参与的开源项目写在简历上有吸引力。 - -> 当然这里不是pua大家一定要参加开源。只是参与贡献的人越多，开源项目就能做的更好，很多开源其实用户能想到的问题作者早就想过了。 -但是往往受限于作者个人的精力和社区的发展。开源迭代非常慢，甚至是很多功能不得不被砍掉。 -另一方面，目前作者的技术路线主要是云原生开发，对java的跟进也非常滞后。因此推荐主线java的同学参与进来推进smart-doc的发展。 - -# smart-doc开源参与要求 -- 无技术硬性要求，即便是萌新不知道怎么修改处理源代码，只要你愿意参与，smart-doc都会指导你去慢慢的修改相关issue. -- 英文注释提交代码，smart-doc已经不仅仅是只有国内用户使用的工具了，我们也有海外用户，因此要求采用英文提交代码注释(不会可以百度、google介入翻译) - -# 怎么参与 -- 加入smart-doc的技术交流群联系作者 -- 也可以提pr, 当然pr也要求写英文注释 - -# 成功参与开源者案例 -smart-doc当中也有比较成功的参与者案例，[netdied](https://github.com/netdied)同学作为一个在校生从2019年加入 -smart-doc开源，2021年拿到小米秋招offer，面试官面试的时候对他的这段开源经历非常感兴趣。 - -# 开源参与者内推 -成都这边参与smart-doc的开源者，smart-doc作者可以帮忙内推到部分知名企业，因此鼓励大家积极参与开源。 \ No newline at end of file + +欢迎来到smart-doc社区！感谢您为smart-doc贡献代码、文档及案例！ +smart-doc自2018年开源以来，受到社区很多小伙伴的关注。 衷心地希望越来越多的社区同学能参与到smart-doc项目中来， +我们一起把smart-doc做好！ + +# 如何贡献？ +如果您想为smart-doc 做出贡献，可以按照以下步骤进行： + +1、在GitHub上Fork smart-doc的代码库到您的个人仓库中。 + +2、Clone您fork的项目到本地仓库，创建其他分支以进行修改。 + +3、在本地环境中运行smart-doc，并确认所做的改动是否生效。可参考 快速开始 了解如何启动smart-doc并生成API文档。 + +4、完成修改后，推送提交并提交Pull Request给smart-doc的主仓库。请参考Pull Request流程 来提交合并请求。 + +5、等待社区Committer审核并合并您的Pull Request。 + +6、如果合并成功，恭喜您已经成功做出了贡献！ + +# 注意的事项 +在为smart-doc 提交贡献时，请注意以下事项： + +- 如果您想添加新功能或者功能升级，请先开Issue讨论。 + +- 为了方便作者审核代码，建议每个Pull Request只提交单一问题的修复或者功能添加，避免大规模变更。 + +- smart-doc作为一个为全球开发者服务的工具，提交代码时请使用英文注释，也是方便社区更好的做国际化推广。 + +- 请遵守代码风格约定，确保代码可读性和易维护性。 + +- 请确保所有提交的代码都有单元测试覆盖，以确保代码质量。 + +- 如有必要，更新相应的文档以反映您的更改。 + +- 最后，我们欢迎任何形式的贡献，包括但不限于代码、文档、Issue 提出等 + +# Code review +所有的代码都需要经过Committer进行review。以下是我们推荐的一些原则： +- 可读性：所有提交请遵循良好的代码规范、文档规范。 +- 优雅性：代码简练、复用度高，有着完善的设计。 +- 测试：对于普通的方法在smart-doc上添加单元测试，对于用户接口代码请在[smart-doc-example-cn](https://github.com/smart-doc-group/smart-doc-example-cn) +添加测试用例并完成提交测试验证。 + +# 案例分享 +我们非常欢迎您分享任何关于smart-doc的使用案例。欢迎大家投稿，分享smart-doc的使用案例。 +对于优秀的案例分享者，社区也会后续也会给予一些奖励。 + +# 参与社区讨论 +如果您在使用smart-doc中遇到任何问题，欢迎到[Discussions](https://github.com/TongchengOpenSource/smart-doc/discussions)进行交流互动。 +也欢迎在这里帮助其他使用者解答一些使用中的问题。 + +Discussion分类： +- Announcements：smart-doc官方公告。 +- Help：使用smart-doc中遇到问题，想在社区寻求帮助。 +- Ideas：关于smart-doc的一些想法，欢迎随时交流。 +- Show and tell：可以在这里展示任何跟smart-doc相关的工作，例如一些工具、案例等。 diff --git a/docs/zh-cn/community/developer.md b/docs/zh-cn/community/developer.md new file mode 100644 index 0000000..87b4fda --- /dev/null +++ b/docs/zh-cn/community/developer.md @@ -0,0 +1,66 @@ + +# 社区角色 +smart-doc社区包含Maintainer、Committer、Contributor等角色，每种角色的标准定义如下。 + + +## Maintainer +对smart-doc项目演进和发展做出显著贡献的个人。 + +成为 Maintainer 的标准： +- 完成多个关键核心功能模块设计与开发，是项目的核心开发人员； +- 持续的投入和激情，能够积极参与社区、官网、Issue、Pull Request(PR) 、Discussion 等项目相关事项的维护； +- 在社区中具有非常好的影响力。 + +成为Maintainer，您也将获得如下权利： +- 具有Smart-doc GitHub 仓库管理权限。 +- 参与新晋Committer或Maintainer的提名及投票。 + +## Committer +是对smart-doc社区某些特定领域做出突出贡献的人 + +成为Committer的标准： +- 能够长时间地并持续性地贡献Issue、PR 代码、测试用例、文档、案例）； +- 参与重要 Feature 的讨论、设计、开发、测试； +- 参与 Code Review。 + +成为Committer，您也将获得如下权利： +- 具有smart-doc GitHub仓库write权限。 +- 参与smart-doc演进、发展的讨论，及核心模块设计评审等。 + +## Contributor +是对smart-doc项目有贡献的个人。 + +成为Contributor的标准： +- 提交过PR并被合并，包括不限于文档、代码、案例等； +- 在iLogtail开源社区参与相关问题讨论，并能积极回复。 + +## 如何成为Contributor及Committer +只要您对smart-doc项目有兴趣，每个人都可以成为smart-doc项目的Contributor。 +您可以从贡献文档开始参与社区贡献，并逐步参与代码的贡献。 +如果您成为了smart-doc Contributor并且持续地做出贡献，达到了Committer的要求，我们将邀请您成为smart-doc Committer. + +# smart-doc开发团队 +感谢所有开发者对社区的贡献！我们会定期将所有贡献者的名字进行展示，当然也可以自己提交 PR 添加。 +> 注：排名不分先后。如有遗漏，请提交 PR 添加。 + +## PMC(项目管理委员会，Project Management Committee) +- Yu Sun(@shalousun) + +## Committer +社区目前处理迁移建设中，等待社区文档完善后评审。 + +## Contributor +https://github.com/TongchengOpenSource/smart-doc/graphs/contributors + + + + + + + + + + + + + From 8c74bf04c436b137f800ee02fc9c7d6e4dc8c325 Mon Sep 17 00:00:00 2001 From: shalousun <836575280@qq.com> Date: Wed, 18 Oct 2023 19:13:39 +0800 Subject: [PATCH 2/2] add: update contributing --- docs/zh-cn/community/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh-cn/community/contributing.md b/docs/zh-cn/community/contributing.md index 8a15215..d9294ea 100644 --- a/docs/zh-cn/community/contributing.md +++ b/docs/zh-cn/community/contributing.md @@ -10,7 +10,7 @@ smart-doc自2018年开源以来，受到社区很多小伙伴的关注。 衷心 2、Clone您fork的项目到本地仓库，创建其他分支以进行修改。 -3、在本地环境中运行smart-doc，并确认所做的改动是否生效。可参考 快速开始 了解如何启动smart-doc并生成API文档。 +3、在本地环境中运行smart-doc，并确认所做的改动是否生效。可参考 [快速开始](https://smart-doc-group.github.io/#/zh-cn/start/quickstart) 了解如何启动smart-doc并生成API文档。 4、完成修改后，推送提交并提交Pull Request给smart-doc的主仓库。请参考Pull Request流程 来提交合并请求。