iLogtail

1769
下载
iLogtail 是阿里云日志服务(Log Service)中的一款高性能、可扩展的日志采集工具。它被设计用于实时收集、解析和传输各类日志数据,支持多种数据源和复杂的日志处理场景,广泛应用于分布式系统、Web 服务器、应用程序等环境中的日志管理。

贡献指南


欢迎来到 iLogtail 的社区!感谢您为iLogtail贡献代码、文档及案例!

iLogtail 自从开源以来,受到了很多社区同学的关注。社区的每一个 Issue、每一个 pull request (PR),都是在为 iLogtail 的发展添砖加瓦。衷心地希望越来越多的社区同学能参与到 iLogtail 项目中来,跟我们一起把 iLogtail 做好。

行为准则

参与 iLogtail 社区贡献,请阅读并同意遵守阿里巴巴开源行为准则,共同营造一个开放透明且友好的开源社区环境。

贡献流程

我们随时欢迎任何贡献,无论是简单的错别字修正,BUG 修复还是增加新功能,包括但不限于代码、文档、案例等任何形式的社区互动。我们也同样重视与其它开源项目的结合,欢迎在这方面做出贡献。

如何入手?

如果您是初次贡献,可以先从 good first issue 列表中认领一个相对小的任务来快速参与社区贡献。

认领方式: 您可以直接在相应 Issue 中回复参与意愿,然后参照下面的 GitHub 工作流指引解决 issue 并按照规范提交 PR,通过 review 后即可合入到 main 分支。

GitHub 完整工作流

我们使用 main 分支作为我们的开发分支,这代表它是不稳定的分支。稳定版本归档在 Release 中,每发布一个 Release 版本,都会打上对应版本 Tag

创建/认领 Issue

我们使用 GitHub Issues 以及 Pull Requests 来管理/追踪需求或者问题。如果您希望开发新的特性、功能完善,或者发现了代码的 BUG,或者文档的增加、完善,或者希望提建议等,都可以创建一个 Issue;也可以认领我们发布出来的一些 Issue。

新建的 Issue 请按照模板规范填写内容,以便我们更好地理解您需求。另外,也需要您打上对应标签,方便我们进行分类管理。

设计交流

如果您的 PR 包含非常大的变更(比如模块的重构或者添加新的组件),请务必发起详细讨论,编写详细的文档来阐述其设计、解决的问题和用途,达成一致后再进行变更。您可以在 Issue 或 Discussions ideas 中给出详细的设计。如果需要我们的支持可以扫描加入钉钉群,我们可以提供一对一的交流。

对于一些小的变更,也请在 Issue 中简单描述您的设计。

开发测试

设计定稿后,即可进行开发流程。下面是开源贡献者常用的工作流(workflow):

  1. iLogtail 仓库 fork 到个人 GitHub 下。
  2. 基于个人 fork 分支进行开发、测试工作。详细流程:
    1. 保持个人 main 分支跟 iLogtail 主仓库 main 分支及时同步。
    2. 将 fork 后的个人仓库 clone 到本地。
    3. 创建新的开发分支,并进行开发。请确保对应的变更都有 UnitTest 或 E2E 测试
    4. 在本地提交变更。注意 commit log 保持简练、规范,提交的 email 需要和 GitHub 的 email 保持一致。
    5. 将变更 push 到远程个人分支。
  3. 向 iLogtail main 分支创建一个 pull request (PR),在进行较大的变更的时候请确保 PR 有一个对应的 Issue,并进行关联。
    1. 发起 PR 前请进行如下规范性检查:代码/文档风格编码规范依赖包许可证文件许可证
    2. 为了更好的进行版本管理,对于一些独立的特性或者关键BUG修复,请提交Changelog.

注意一个 PR 尽量不要过于大,如果的确需要有大的变更,可以将其按功能拆分成多个单独的 PR。

若您是初次提交 PR,请先签署 CLA(PR 页面会有自动回复指引)。在提交 PR 后,系统会运行持续集成,请确保所有的 CI 均为 pass 状态。一切就绪后,我们会为 PR 分配一个或多个 reviewer,review通过后即可合入 main。

在合并 PR 的时候,请把多余的提交记录都 squash 成一个,保证最终的提交信息的简练、规范。

标签

我们使用标签来进行 Issue、PR、Discussion 的管理。您可以根据实际情况打上对应的标签。

  • 全新特性,对应 label: feature request。
  • 现有功能完善,对应 label: enhancement。
  • 适合新手开发,对应 label: good first issue。
  • Bug,对应 label: bug。
  • 测试框架或测试用例,对应 label: test。
  • 配置样例或K8s部署案例,对应 label: example config。
  • 文档(document),对应 label: documentation。
  • 案例类,对应 label: awesome ilogtail。
  • 回答、解决问题,对应 label: question。我们建议优先提到 Discussions 中讨论。

以下为附加标签:

  • 希望社区参与贡献,对应 label: community。
  • 核心功能开发或变更,对应 label: core。

Code review

所有的代码都需要经过 committer 进行 review。以下是我们推荐的一些原则:

  • 可读性:所有提交请遵循我们的代码规范插件文档规范
  • 优雅性:代码简练、复用度高,有着完善的设计。
  • 测试:重要的代码需要有完善的测试用例(单元测试、E2E 测试),对应的衡量标准是测试覆盖率。

配置分享

除了共享代码,您也可以为我们的配置样板库做出贡献。

example_config/data_pipelines目录包含场景化的采集配置模版,重点突出processor / aggregator插件功能。如您对某些常见日志(如Apache、Spring Boot)的处理有一定心得,可以参考已有样例和README进行提交。

k8s_templates目录包含完整的K8s部署案例,从源到典型处理到输出,以input / flusher插件进行划分。如您对某些常见的日志处理场景(如将数据采集到Elastic Search、Clickhouse)的部署有一定心得,可以参考已有样例和README进行提交。

案例分享

我们也欢迎您分享任何关于 iLogtail 的使用案例。我们在知乎建立了专栏 iLogtail社区,欢迎大家投稿,分享 iLogtail 的使用案例。

  1. 在知乎写文章,例如一文搞懂 SAE 日志采集架构
  2. 推荐自己的文章到“iLogtail社区”专栏。
  3. GitHub上修改use-cases.md并发起PR,Label选awesome ilogtail。

参与社区讨论

如果您在使用 iLogtail 中遇到任何问题,欢迎到 Discussions 进行交流互动。也欢迎在这里帮助其他使用者解答一些使用中的问题。

Discussion 分类:

  • Announcements:iLogtail官方公告。
  • Help:使用 iLogtail 中遇到问题,想在社区寻求帮助。
  • Ideas:关于 iLogtail 的一些想法,欢迎随时交流。
  • Show and tell:可以在这里展示任何跟 iLogtail 相关的工作,例如一些小工具等。

联系我们


observability.cn Authors 2024 | Documentation Distributed under CC-BY-4.0
Copyright © 2017-2024, Alibaba. All rights reserved. Alibaba has registered trademarks and uses trademarks.
浙ICP备2021005855号-32