Skip to content

Latest commit

 

History

History
202 lines (140 loc) · 4.66 KB

关于合作开发.md

File metadata and controls

202 lines (140 loc) · 4.66 KB

合作开发指南

本项目在 GitHub 开源，为了更好地进行合作开发，计划制定相关教程和规范。以下是当前开发原则、内容规范及开发流程。规范会根据需求不断调整，欢迎提出改进建议！

开发原则

  1. 简洁易懂：确保代码和文档简洁明了，方便快速理解重点。
  2. 保证正确性：对自己的修改负责，可以多次修改，直到合适为止。
  3. 奥卡姆剃刀原则：如无必要，勿增实体。尽量基于 Obsidian 原生功能进行开发，避免过度依赖复杂插件。
  4. 优先记录：若时间紧迫，可将内容先归类到对应一级文件夹，后续再整理完善。

开发方式

方式一：加入仓库成为合作者

适合频繁提交的开发者，直接成为 GitHub 仓库合作者：

  1. 提交申请，获得仓库写权限。
  2. 在本地或 Codespaces 中修改文件，随时同步到主分支。

方式二：通过 Pull Request 提交更改

适合偶尔修正或补充内容的开发者：

  1. Fork 仓库到自己的 GitHub。
  2. 在 Fork 的仓库中修改或添加内容。
  3. 提交 Pull Request，等待合并。

内容规范

1. 层级与双链

  • 添加双链：所有词条需按照层级顺序，添加上级目录的双链。例如：
dlink: [[不定积分]]

说明：积分表 词条属于 微积分 的 不定积分，则需通过 dlink 属性记录所属层级。

2. 内容原子化与引用

  • 原子化：最底层内容尽量以词条形式呈现，每个词条仅包含一个基本概念。

  • 引用内容：整合多个词条时使用引用语法：

    ![[向量]]

  • 结构规范：词条主要内容直接写在开头，无需标题；间接内容用多级标题（如性质、例子、推广）。

3. 文档结构

建议每篇文档包含以下部分：

  • 简介：引用词条或以文档名为一级标题。
  • 定义：引用或补充相关词条。
  • 推导：公式或理论的证明过程。
  • 性质：描述概念的核心性质。
  • 例题：典型应用示例。
  • 推论：从性质或定义推导出的结论。
  • 应用：实际应用场景或扩展知识点。

4. YAML 配置项

每篇文档头部建议包含以下 YAML：

tags: [数学, AI]          # 标签，如“数学”或“AI”
dlink: [[父级目录]]       # 双链，记录父级目录或相关词条
aliases: [别名, 简写]      # 别名，例如英文名或简写
chapter: 章节序号          # 对应章节序号
urlink: [外部链接]         # 外部参考链接（如 Wikipedia）
author: [作者1, 作者2]     # 作者信息
datetime: 2024-11-30       # 创建时间

准备条件

  1. 确保拥有 GitHub 账号。

  2. 安装 Git 命令行工具。

  3. 配置 Obsidian Git 插件。

  4. 如果在国内，请解决网络问题。

  5. 从 GitHub 克隆项目：

    git clone https://github.com/your-repo.git

开发步骤

1. 拉取（Pull）

从远程仓库拉取最新的修改：

git pull origin main

2. 提交（Commit）

将本地的修改提交到版本管理：

git add .
git commit -m "描述修改内容"

3. 推送（Push）

将本地修改推送到远程仓库：

git push origin main

4. 冲突处理

冲突发生时，需要手动解决。处理步骤：

  1. 查看冲突内容：

    git status

  2. 修改冲突的文件，选择正确的合并方式。

  3. 提交修复后的内容：

    git add <文件名>
git commit -m "解决冲突"
git push origin main

子模块（Submodule）使用

添加子模块

  1. 进入父项目目录：
cd "E:\Note"
  1. 添加子模块：
git submodule add https://github.com/PKM-er/Pkmer-Math.git Math
  1. 初始化子模块：
git submodule init
git submodule update --init
  1. 提交更改：
git add .
git commit -m "添加 Math 子模块"
git push

更新子模块

当 Math 仓库更新时，可使用以下命令同步：

git submodule update --remote

.gitignore 配置

以下为推荐的 .gitignore 配置，用于排除本地个性化文件：

# 忽略用户个性化配置
.DS_Store
.history
.trash

# 忽略部分 Obsidian 文件
.obsidian/*
.obsidian/plugins/*
.obsidian/snippets
.vscode

# 忽略 Git 子模块配置文件（如无必要）
.gitmodules

通过上述内容，开发者可以选择合适的参与方式（合作者或 Pull Request），并遵循开发规范和步骤高效协作。欢迎对本项目提出改进建议！