Oh My Fish 项目贡献指南与技术规范详解

Oh My Fish 项目贡献指南与技术规范详解

oh-my-fish The Fish Shell Framework 项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-fish

项目概述

Oh My Fish 是一个基于 Fish Shell 的框架管理工具，它提供了插件和主题管理系统，让用户可以轻松扩展 Fish Shell 的功能。本文将深入解析该项目的贡献流程和技术规范，帮助开发者更好地参与项目开发。

问题报告与讨论规范

提交问题报告

当遇到问题时，提交报告需要包含以下关键环境信息：

• 操作系统类型及版本（如：Arch Linux）
• Fish Shell 版本（通过 fish --version 获取）
• Oh My Fish 版本（通过 omf --version 获取）
• Git 版本（通过 git --version 获取）

这些信息对于问题复现和诊断至关重要。

问题讨论流程

对于新功能或重大变更建议，建议先发起讨论：

1. 详细描述功能需求或变更动机
2. 说明预期实现方案
3. 讨论可能的替代方案

代码仓库结构说明

本项目核心仓库包含：

• Oh My Fish 框架主体
• 引导安装程序

注意：特定插件或主题的问题应优先在其对应的仓库中提交。

提交信息规范

格式要求

1. 使用现在时态（如："add feature"而非"added feature"）
2. 添加子系统前缀（如："registry: update theme loader"）
3. 首行不超过50个字符
4. 可使用表情符号增强可读性

示例

theme: add dark color scheme 🎨

代码风格指南

基础规范

• 使用2个空格缩进（不同于Fish Shell官方的4空格规范）
• 保持代码简洁清晰

控制流写法

条件语句应采用换行+缩进格式：

set -q config_file
  and source $config_file
  or echo "Config not found"

函数定义规范

1. 命名参数使用 -a 标志：

function install -a package_name
  # 安装逻辑
end

2. 添加描述信息使用 -d 标志：

function update -d "Update all installed packages"
  # 更新逻辑
end

3. 命名空间前缀：使用包名作为前缀防止命名冲突

function myplugin_utils.helper_func
  # 工具函数
end

私有函数实现方案

Fish Shell 没有原生私有函数支持，可采用以下方案：

1. 双下划线前缀法：

function __myplugin_internal_func
  # 内部实现
end

2. 动态删除法：

function public_api
  function __temp_impl
    # 临时实现
    functions -e __temp_impl  # 使用后立即删除
  end
  
  __temp_impl
end

最佳实践建议

1. 模块化开发：将功能拆分为独立文件
2. 兼容性检查：在关键操作前验证环境依赖
3. 错误处理：提供有意义的错误提示
4. 性能优化：避免在启动脚本中执行耗时操作

通过遵循这些规范，开发者可以确保代码质量与项目风格保持一致，提高协作效率。

oh-my-fish The Fish Shell Framework 项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-fish