Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
137 lines (97 loc) · 6.98 KB

CONTRIBUTING.md

File metadata and controls

137 lines (97 loc) · 6.98 KB

向 ClassIsland 贡献代码

流萤比心

❤️感谢您向 ClassIsland 做出贡献，您可以为 ClassIsland 项目做出包括但不限于反馈 Bug、提出功能请求、贡献代码等贡献。在进行贡献前，请务必阅读以下指南。

反馈 Bug

如果在使用 ClassIsland 的过程中遇到 Bug，可以在Issues中提交 Bug 反馈。

请务必准确地按照 Issues 模板中的要求和示例填写相关字段，否则开发者可能难以诊断您遇到的问题。

提交功能请求

如果您有关于 ClassIsland 新功能的想法，欢迎在Issues提交功能请求。提交的功能请求必须满足以下要求：

  • 提交的功能在应用最新的版本号版本，和最新提交中还没有实现。
  • 没有与此功能请求重复或相似的Issues 。
  • 提交的的功能是用户广泛需要的，插件不能替代的，且没有超出 ClassIsland 作为灵动课表的开发目标，而非添加与课表及教学辅助无关的内容。

提交的功能请求会按照以下流程处理：

flowchart LR
    Receive["接受功能请求 Issue"]
    --> Traige["审查功能请求"]
    --> |"通过"| StartVoting["移除“待讨论”标签，进入投票"]
    --> |"根据票数等因素被选中"|Milestone["进入开发里程碑"]
    --> Wip["进入开发"]
    --> RmVoting["移出投票"]
    --> Completed["开发完成"] -->|"completed"| Close
    Traige --> |"重复/不切实际/严重偏离开发路线"| Reject["不通过"]
    -->|"not planned"| Close["关闭 Issue"]
    Traige --> |"需要进一步讨论"| Discus["进行讨论"] --> Traige
    Discus --> |"14天内没有更多动态"| Reject
Loading

您可以在投票页面为您想要的功能进行投票，开发者会结合多种因素，优先处理票数较高的功能请求。需要注意，受限于时间和精力，票数高的功能请求不是100%会被开发者优先处理，还请谅解。如果您有能力，欢迎为本项目贡献代码。

贡献代码

在为 ClassIsland 贡献代码之前，请务必阅读以下指南。

下面是一些有用的资源：

贡献准则

您为 ClassIsland 贡献的功能须遵循以下准则：

  • 稳定： 您贡献的功能需要能尽可能稳定工作。
  • 具有泛用性： 您贡献的功能需要面向大部分用户。如果您贡献的功能专用性较强，可以考虑以开发 ClassIsland 插件的形式提供此功能。
  • 如果您贡献的功能比较激进，请添加功能开关，并默认禁用此功能。 激进的功能一般指会对正常授课产生较大影响的功能。
  • 能用： 在提交补丁前，请在本地测试您实现的功能是否能正常使用。
  • 尽量不要提交仅包含文案修复的补丁。

补丁质量

随着本项目的规模逐渐扩大，有些用户提交了一些低质量的补丁。这些补丁有的完全不能实现预期的功能，有的甚至根本不能通过编译，浪费了开发者的时间和精力对这些补丁进行代码审阅和问题排查。我们接受有瑕疵的补丁， 但我们希望您在提交补丁前，您的补丁至少应该满足以下的要求：

  • 实现的功能能够工作，在提交补丁前请至少在本地机器测试一次补丁的功能是否可以正常工作。
  • 我们不建议在没有人为干预的情况下完全地使用生成式人工智能实现您要贡献的功能。

如果您持续提交低质量的补丁，我们可能会限制您继续向本项目/组织提交补丁。

分支与开发周期

ClassIsland 代码仓库目前具有以下分支：

  • master：ClassIsland 主要开发分支。
  • x.x（版本号，如 2.0）：ClassIsland 对分支版本对应的版本的维护分支。

当开始下个版本的 ClassIsland 时，会将当前的主分支分叉到对应的维护分支。在开发下一个版本的 ClassIsland 过程中，也会在维护分支上并行维护当前稳定版本的功能，如以下示意图所示：

Note

以下图表的提交id和标签名称仅供示意。

%%{init: {'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'master'}} }%%
gitGraph
    commit
    commit tag: "2.0.0.0（稳定通道）"
    commit
    commit
    commit tag: "2.0.0.1（稳定通道）"
    branch 2.0
    commit
    commit
    commit tag: "2.0.0.2（稳定通道）"
    checkout master
    commit
    commit
    commit tag: "2.0.1.0 （测试通道）"
    commit
    merge 2.0
    commit
    commit tag: "2.1.0.0 （稳定通道）"
    branch 2.1
    commit
    commit
    commit tag: "2.1.0.1 （稳定通道）"
    checkout master
    commit
    commit
    merge 2.1
    commit tag: "2.1.1.0 （测试通道）"
Loading

由于不同开发分支上的代码接口可能存在差异。因此，根据您做出的贡献类型，您需要选择不同的基础分支。

以下类型的贡献建议以当前的维护分支为基础分支：

  • 修复稳定版中的 Bug
  • 对稳定版中的功能进行小幅度的优化

以下类型的贡献建议以 master 为基础分支：

  • 添加新的功能
  • 对代码进行重构
  • 其它对 ClassIsland 进行较大改动的贡献
  • 修改README等文档

提交

在本代码仓库提交时，请尽量遵守约定式提交规范。考虑到目前 ClassIsland 项目规模较大，请在进行提交时考虑为提交添加范围。

合并更改

在进行合并之前，请先测试您贡献的代码，确保您贡献的代码能稳定运作。

您可以向本项目发起 Pull Request 来合并您的更改。在发起 Pull Request 时，请简要地描述您做的更改，并最好附上您实现的功能的演示截图/视频。

还有疑问？

您可以加入QQ群与开发者和其他用户讨论。