Skip to content

Commit

Permalink
docs: add release polocy document English version
Browse files Browse the repository at this point in the history
Signed-off-by: peefy <[email protected]>
  • Loading branch information
Peefy committed Nov 28, 2023
1 parent d1b65d4 commit 88ce8f1
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 50 deletions.
50 changes: 25 additions & 25 deletions docs/community/release-policy/kcl.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,39 @@
# KCL Release Policy

KCL 开发团队采用 [语义化版本](https://semver.org/lang/zh-CN/) 来简化管理。版本格式:主版本号.次版本号.修订号。版本号递增规则如下:主版本号对应不兼容的 API 修改,次版本号对应向下兼容的功能性新增,修订号对应向下兼容的问题修正。总体目标是每一个半月发布一个特性增强的次要版本,根据需要不定期发布其他版本的修订。
The KCL development team uses [Semantic Versioning](https://semver.org/) to simplify management. The version format follows the pattern of major.minor.patch. The version increments as follows: major version for incompatible API changes, minor version for backward-compatible functionality additions, and patch version for backward-compatible bug fixes. The overall goal is to release a minor version with feature enhancements every six months, with occasional patch versions as needed.

KCL 项目版本发布策略如下:
The KCL project version release strategy is as follows:

- 主版本号:当进行重大的架构调整或者加入重大的新功能时,需要提升主版本号。对于 KCL 项目来说,目前的主版本号为 0。
- 次版本号:当添加的功能和特性有较大的变化时,提升次版本号。目前的次版本号为 5,2023 年度会相继发布 0.5, 0.6, 0.7 版本。
- 修订号:通过修复漏洞或者改进性能来更新程序时,会提升修订号,修订号从 0 开始计数以此加 1。
- 发布周期:在未达到 v1.0.0 版本之前,计划每隔 3 个月发布一个新的次要版本。在此期间,需要持续收集用户反馈,并进行必要的修复和改进。
- 发布流程:在发布新版本之前,需要进行严格的测试和审核,确保新版本的质量。封板并测试完成后,会在 Github 上发布新版本的源代码,二进制和镜像,并提供详细的文档和使用指南。
- 版本支持:我们将对最新的版本提供长期支持,包括漏洞修复和安全更新。对于旧版本,我们将提供有限的支持,仅在必要时进行修复。
- Major Version: The major version is increased when there are significant architectural changes or major new features. The current major version for the KCL project is 0.
- Minor Version: The minor version is increased when there are significant changes to added features and functionalities. The current minor version is 5, and versions 0.5, 0.6, and 0.7 will be released in the year 2023.
- Patch Version: The patch version is increased when there are updates to fix bugs or improve performance. The patch version starts from 0 and increments by 1.
- Release Cycle: Before reaching version 1.0.0, the plan is to release a new minor version every 3 months. During this period, user feedback will be continuously collected, and necessary fixes and improvements will be made.
- Release Process: Before releasing a new version, rigorous testing and review are conducted to ensure the quality of the new version. After finalizing the release and completing the testing, the source code, binaries, and images of the new version will be published on Github, along with detailed documentation and usage guides.
- Version Support: Long-term support will be provided for the latest version, including bug fixes and security updates. Limited support will be provided for older versions, with fixes only done when necessary.

## 发布流程与规则

- 特性开发:main 分支主干开发,分支发布,block 用户使用的问题和严重的 bug, 安全隐患,高优先级解决,尽可能保持在一周内收敛,高于一般的功能研发。
- 迭代周期:我们的迭代周期通常为 3 个月,即每 3 个月发布一个新的次要版本。
- 版本规划:发版前两周产出 alpha 版本,前一周产出 beta 版本,alpha 版本仍可进行特性合并,beta 版本只合并错误修复,最终产出正式版本并打 tag 作为长期保存的 release 分支。
- 发版计划:在每个发布周期开始时制定详细的发版计划(Github Milestone),包括发布日期、版本号、功能列表和测试计划等。需要尽可能地遵守发版计划,确保按时发布新版本。
- 发布前测试:在发布新版本之前,需要进行全面的测试,包括单元测试、集成测试,模糊测试,压测,用户验收测试等。只有经过测试并无问题后,我们才会发布新版本。
- 版本回滚:如果在发布后发现了严重的问题,需要立即回滚版本,并尽快修复问题。并通过邮件、社交媒体等渠道及时通知用户,并提供解决方案。
- 发布文档:需要在发布时提供详细的文档,包括发布说明、更新日志、API 文档和使用指南等,帮助用户了解和使用新版本。在 KCL 中,我们统一在 KCL 网站进行维护。
- 版本兼容性:在发布新版本时,需要尽可能保持兼容性,以确保用户无需进行过多的修改和适应。KCL 还没有达到 v1,暂时没有兼容性保证。KCL 的目标是尽可能少地进行重大更改,不应轻率地考虑对语言的更改,为了语言自身更好地演进和发展,一般认为更改具有重大好处时才会进行(较好地解决了目标场景的问题或者提升了绝大用户的使用体验)。对于可能引入兼容性问题的功能或变更,提供相应的提示和解决方案,同时会提供逐步升级的指南或提供自动迁移的工具,以帮助用户平滑地迁移到新版本。
- Feature Development: Main branch development, branch releases, block user issues, critical bugs, security vulnerabilities, and high-priority fixes. It is given higher priority over general feature development and should be completed within a week.
Iteration Cycle: The iteration cycle is typically 3 months, with a new minor version released every 3 months.
- Version Planning: Two weeks before the release, an alpha version is produced, followed by a beta version one week before the release. Alpha versions can still include feature merging, while beta versions only include bug fixes. The final release version is tagged as a long-term saved release branch.
- Release Plan: A detailed release plan (Github Milestone) is created at the beginning of each release cycle, including release dates, version numbers, feature lists, and testing plans. The release plan should be followed as closely as possible to ensure timely releases.
- Pre-release Testing: Comprehensive testing, including unit testing, integration testing, fuzz testing, stress testing, and user acceptance testing, is conducted before releasing a new version. The new version is only released when it passes all tests without any issues.
- Version Rollback: If serious issues are discovered after the release, the version will be rolled back immediately, and the issues will be fixed as soon as possible. Users will be promptly notified through email, social media, etc., and provided with solutions.
- Release Documentation: Detailed documentation, including release notes, update logs, API documentation, and usage guides, is provided during the release to help users understand and use the new version. In KCL, this documentation is maintained on the KCL website.
- Version Compatibility: When releasing a new version, compatibility is maintained as much as possible to minimize the need for modifications and adaptations by users. Since KCL has not reached version 1 yet, there are no compatibility guarantees at the moment. The goal of KCL is to minimize major changes unless they provide significant benefits, such as solving problems in the target scenarios or improving the overall user experience. For features or changes that may introduce compatibility issues, appropriate prompts and solutions will be provided. Gradual upgrade guides or automated migration tools will be offered to help users smoothly transition to the new version.

## 发布组件
## Release Components

![](/img/docs/community/release-policy/kcl-components.png)

每次版本发布时,KCL 相关所有组件保持一个依赖同一个 KCL 核心主要版本,整体采用树形结构组织依赖顺序发布并进行回归测试,直到发布测试完成,尽力避免三角依赖,禁止循环依赖。
For each version release, all related components of KCL depend on the same major version of the KCL core. The dependencies are organized in a tree structure and released and regression tested in a specific order until the release testing is completed, with efforts made to avoid triangular dependencies and prohibit circular dependencies.

## 一个 Feature 的生命周期
## Lifecycle of a Feature

- 设计方案/文档:通过 Issue 回答清楚这个 feature 的动机是什么,它解决什么问题以及目标是什么,用户需求和用户故事是怎样的;这个 feature 做什么,如何做,难度怎样,需要多长时间,依赖项,需要做什么测试等。(Tips: 大的设计尽量拆分成小的设计,通过权衡和广泛的调研找到一个简单且可持续的解决方案,并且具备一定得到可扩展以适应未来的业务或技术变化,通过持续讨论和方案评审确定最终设计)。
- 编写代码:通过高频小改动进行迭代、持续沟通和协作,提前设计单元测试、集成测试和 benchmark 等测试用例,确保编写代码 100% 测试覆盖,注释完整和逻辑清晰,并通过 Demo 演示持续收集反馈。
- 文档撰写:在 [KCL 网站](https://kcl-lang.io) 中更新用户文档。
- 测试和反馈:在发布功能之前,让一些同行/用户通过**随循文档**而不是口述来尝试和测试这些新功能。接收反馈并改进。
- 发布和公告:撰写 Release Note, PR 文章,场景和新特性解读等以及渠道宣发等。
- Design and Documentation: Clearly answer the motivations, problems to be solved, and goals of the feature through issues. Define user requirements and user stories. Specify what the feature does, how it is implemented, its difficulty level, estimated time, dependencies, and testing requirements. (Tips: Split large designs into smaller ones, find a simple and sustainable solution through trade-offs and extensive research, and ensure scalability to adapt to future business or technical changes. Finalize the design through continuous discussions and design reviews).
- Code Implementation: Iteratively develop the feature through frequent small changes, continuous communication and collaboration. Design unit tests, integration tests, and benchmark tests in advance to ensure 100% test coverage, complete comments, and clear logic. Continuously collect feedback through demonstrations.
- Documentation Writing: Update user documentation on the KCL website.
- Testing and Feedback: Before releasing the feature, allow some peers/users to try and test these new features through written documentation rather than oral descriptions. Receive feedback and make improvements.
- Release and Announcements: Write Release Notes, PR articles, interpret scenarios and new features, and promote through various channels.

> 注:以上所有信息全是公开的,需要透出给所有社区研发者进行参与、讨论和贡献。
> Note: All the above information is public and should be made available for all community developers to participate, discuss, and contribute.
Loading

0 comments on commit 88ce8f1

Please sign in to comment.