diff options
| -rw-r--r-- | CONTRIBUTING.md | 58 | ||||
| -rw-r--r-- | CONTRIBUTING_zh_CN.md | 66 | ||||
| -rw-r--r-- | README.md | 92 | ||||
| -rw-r--r-- | README_zh_CN.md | 82 |
4 files changed, 193 insertions, 105 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fbf868..6950355 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,14 @@ # Welcome to Contributing! -Welcome to contributing to `JustEnoughVCS`! Before you begin, please read this guide to ensure a smooth contribution process. +**Before You Begin**: +Thank you for your interest in and support of JustEnoughVCS! If you wish to contribute to the project, please read this guide carefully first. +We warmly welcome and value every contributor's submission, but to ensure a smooth and efficient contribution process, please follow the standardized approach. -## 1. Choose Your Direction + + +## 1. Choose Your Module `JustEnoughVCS` uses a modular architecture that separates core functionality from client tools into different repositories: @@ -26,17 +30,17 @@ Please first understand which module of `JustEnoughVCS` you want to contribute t Fork the repository you want to modify to your GitHub account, then clone it locally using SSH. -For non-`VersionControl` parts, please also clone the core repository using HTTP into a sibling directory to ensure it can reference the `VersionControl` repository. +For non-`VersionControl` parts, please also clone the core repository into a sibling directory to ensure it can reference the `VersionControl` repository. Structure should look like this: ``` . -├── <frontend-name> -│ ├── src/ # Frontend source code -│ ├── Cargo.toml # Rust project configuration -│ └── README.md # Project documentation -└── VersionControl/ # Core library reference +├── <frontend-name> # Frontend & Extensions +│ ├── src/ +│ ├── Cargo.toml +│ └── README.md +└── VersionControl/ # Core library ├── src/ ├── Cargo.toml ├── CONTRIBUTING.md @@ -46,6 +50,14 @@ Structure should look like this: +> [!NOTE] +> +> We currently don't use `git submodule` because the core library and frontends require extensive synchronized modifications +> +> This will transition to `git submodule` approach once the project stabilizes + + + ## 3. Set Up Development Environment Development environment configuration can be found in the documentation of each repository. @@ -60,24 +72,32 @@ For example: The `CommandLine` part uses Rust + Clap to build the command-line p Before submitting, please ensure: -1. Create a feature branch in your forked repository +1. Create a feature branch in your forked repository, and develop based on the repository's `dev` or `docs` branch 2. Implement your feature or fix -3. Write appropriate test cases and pass all tests -4. Submit clear commit messages -5. Create a Pull Request to the main repository +3. Describe your changes in the COMMIT message and push to your fork +4. Create a Pull Request to the main repository's `dev` or `docs` branch + + + +### Note: PRs We Cannot Accept + +Changes we don't expect: + +1. Major changes that haven't been discussed in the Issues section +2. Features that increase rather than reduce mental complexity -### Notes +Wrong merge branches: -- Ensure your code follows the project's coding standards -- Sync with the latest changes from the main repository before submitting PR -- For major changes, it's recommended to discuss the design approach in Issues first +1. Documentation changes merged to the `dev` branch +2. Code changes merged to the `docs` branch +3. Changes merged to the `main` branch -## Finally, Open Source Licenses +## Open Source Licenses -Different `JustEnoughVCS` projects use different open source licenses. For example, the current `VersionControl` uses the very permissive MIT License (see LICENSE-MIT.md file), while `MyVault` uses the `GPLv3` license. +Different `JustEnoughVCS` projects use different open source licenses. For example, the current `VersionControl` uses the MIT License (see LICENSE-MIT.md file), while the GUI part uses the `GPLv3` license. -Thank you for your support of `JustEnoughVCS`! +Finally, thank you for your support of `JustEnoughVCS`! diff --git a/CONTRIBUTING_zh_CN.md b/CONTRIBUTING_zh_CN.md index bf6b3a8..93234f9 100644 --- a/CONTRIBUTING_zh_CN.md +++ b/CONTRIBUTING_zh_CN.md @@ -1,10 +1,14 @@ -# 欢迎您的贡献！ +# 欢迎您对该项目作出贡献！ -欢迎您对 `JustEnoughVCS` 进行贡献！开始之前，请阅读本指南以确保您的贡献流程顺利。 +**写在前面**： +感谢您对 JustEnoughVCS 的关注和支持！如果您希望为项目做出贡献，请先仔细阅读本指南。 +我们非常欢迎并重视每一位贡献 者的提交，但为了确保贡献流程的顺畅高效，请按照规范的方式进行提交。 -## 一、选择您的方向 + + +## 第一步：选择您需要贡献的模块 `JustEnoughVCS` 采用模块化架构，将核心功能与客户端工具分离为不同的代码库： @@ -22,21 +26,21 @@ -## 二、部署项目 +## 第二步：部署项目 请分叉你需要修改的库到您的 GitHub 账户，然后使用 SSH 克隆至本地。 -对于非 `VersionControl` 部分，请将 核心 部分同时以 HTTP 的方式克隆至同级目录，以确保该部分可以引用到 `VersionControl` 仓库。 +对于非 `VersionControl` 部分，请将 核心 部分克隆至同级目录，以确保该部分可以引用到 `VersionControl` 仓库。 结构如下： ``` . -├── <前端名称> -│ ├── src/ # 前端源代码 -│ ├── Cargo.toml # Rust 项目配置 -│ └── README.md # 项目说明文档 -└── VersionControl/ # 核心库引用 +├── <前端名称> # 前端 & 拓展 +│ ├── src/ +│ ├── Cargo.toml +│ └── README.md +└── VersionControl/ # 核心库 ├── src/ ├── Cargo.toml ├── CONTRIBUTING.md @@ -46,37 +50,53 @@ -## 三、部署开发环境 +> [!NOTE] +> +> 目前不使用 `git submodule` 的原因是核心库和前端需要大量的同步修改 +> +> 项目稳定后会转变为 `git submodule` 方式 + + + +## 第三步：部署开发环境 开发环境的配置请参考对应仓库中的文档。 `JustEnoughVCS` 在不同前端方向的技术选型不一样。 -例如：`CommandLine` 部分采用 Rust + Clap 构成命令行程序；而 `MyVault` 图形界面部分采用 Avalonia + .NET。 +例如：`CommandLine` 部分采用 Rust + Clap 构成命令行程序；而图形界面部分采用 Avalonia + .NET。 -## 四、提交您的 PR +## 第四步：提交您的 PR 在此之前，请确保： -1. 在您的分叉仓库中创建功能分支 +1. 在您的分叉仓库中创建功能分支，并基于该仓库的 `dev` 或 `docs` 分支进行开发 2. 实现您的功能或修复 -3. 编写适当的测试用例，并通过测试 -5. 提交清晰的提交信息 -6. 创建 Pull Request 到主仓库 +3. 在 COMMIT 信息中描述您的更改，并推送至您的分叉 +4. 创建 Pull Request 到主仓库的 `dev` 或 `docs` 分支 + + + +### 注意：我们不会接受的 PR + +我们预期外的修改： + +1. 没有在 Issues 栏目中讨论过的大型更改 +2. 不降反增心智复杂度的功能 -### 注意事项 +错误的合并分支： -- 请确保您的代码遵循项目的编码规范 -- 在提交 PR 前，请同步主仓库的最新更改 -- 对于重大更改，建议先在 Issues 中讨论设计方案 +1. 合并到 `dev` 分支的文档内容修改 +2. 合并到 `docs` 分支的代码内容修改 +3. 合并到 `main` 分支的修改 -## 最后、开源协议 +## 开源协议 -`JustEnoughVCS` 不同项目的开源协议并不相同，例如当前的 `VersionControl` 使用的就是最宽松的 MIT License （详见 LICENSE-MIT.md 文件）；而 `MyVault` 则使用的 `GPLv3` 的协议。 +`JustEnoughVCS` 不同项目的开源协议并不相同，例如当前的 `VersionControl` 使用的是 MIT License （详见 LICENSE-MIT.md 文件）；而 GUI部分 则使用的 `GPLv3` 的协议。 @@ -1,13 +1,13 @@ <p align="center"> <a href="https://github.com/JustEnoughVCS/VersionControl"> - <img alt="JustEnoughVCS" src="docs/images/Header_Large.png" width="100%"> + <img alt="JustEnoughVCS" src="docs/images/Header_Large.png" width="100%"> </a> </p> <h1 align="center">JustEnoughVCS</h1> <p align="center"> - A Lightweight, Cross-Functional, Binary-Friendly Centralized VCS. + Lightweight and Binary-Friendly Centralized Version Control System </p> <p align="center"> @@ -17,65 +17,89 @@ </p> > [!WARNING] -> JustEnoughVCS is currently under active development, and features are not yet complete. +> JustEnoughVCS core features are still under development and not yet usable > -> If you are interested in our project, we recommend contacting us directly. +> If you are interested in our project, we recommend contacting us directly. [Contact and Support](#Support) - `JustEnoughVCS` is a lightweight version control system designed for **cross-functional teams**. It allows each member to view and organize files in a file structure **best suited to their functional role**, enabling the team to focus on content creation itself. It primarily serves collaborative scenarios involving large volumes of binary assets, such as **game development** and **multimedia design**. -- [Virtual File System](#virtual-file-system) -- [Sheet System](#sheet-system) -## My Design Philosophy - Also My Humble Opinion 😃 +## Introduction - `JustEnoughVCS` adheres to the "**Just Enough**" philosophy, aiming to achieve collaborative security through architectural design. Centered around a **Virtual File System** and **Sheet Isolation**, it provides each creator with a focused, distraction-free workspace, making collaboration natural and simple. +JustEnoughVCS simplifies binary collaboration by allowing only one person to edit a file at a time. Its architecture keeps you updated on file status, versions, and other relevant information. -## Virtual File System +### 1. Personal View - The Virtual File System is the foundation of `JustEnoughVCS`. Each file is identified by a globally unique `VirtualFileId`, decoupled from its physical path. It comprehensively records: +Each member has their own sheet[^sheet] that maps assets to directory structures. This allows personalized file views. Members can focus on their own workspace without worrying about others moving files or affecting others with their own moves. -- **All historical versions** -- **Description information for each modification** -- **Version number sequence** -- **Current latest version** -- **Current file holder (the member with edit permissions)** +### 2. Asset "Read" and "Write" -### Features +JustEnoughVCS has an intuitive permission model: visible assets can be read, held assets can be modified. -- **Traceable History**: Easily view the history of any version and support rollback. -- **Conflict-Free Collaboration**: Strictly adheres to the **"Acquire First, Edit Later"** principle. Files are **visible** to everyone but **writable** only by the holder, thus preventing conflicts. -- **Pre-Acquisition Validation**: Before acquiring a file, the hash value and version number of the local file are strictly validated to ensure editing starts from the latest version. +[^sheet]: Sheet: A member's personal file structure. Members can have multiple sheets, but only one can be edited in a local workspace[^local_workspace] at a time. +[^local_workspace]: Local Workspace: The local directory where members edit files. -## Sheet System +### 3. Visibility Propagation - The Sheet System acts as a bridge connecting **virtual files** with members' **local workspaces**. It establishes a mapping from `VirtualFileId` to a local `SheetPath`, creating customized file views for each functional role (e.g., programmer, artist, designer) or individual member. +To **share an asset with everyone**, export[^export] its mapping to the reference sheet[^ref_sheet]. After vault[^vault] administrator approval, it becomes visible to all members, who can then import[^import] it to receive updates. -Sheets are divided into two types, primarily differing in permission management: +To share with **specific sheets**, export the asset visibility to those sheets. After approval from the sheet holders, they can receive your updates. -- **Reference Sheet**: Stores files commonly used across the team, serving as a shared resource library. All members can acquire files from it into their own sheets. Members can submit their own files to the Reference Sheet; after approval by an administrator, they are added to the Reference Sheet for other members to import into their own sheets. -- **Member Sheet**: A member's own sheet, used to manage personal projects, tasks, and assets. The member has full management rights over the **sheet structure** (such as adding, moving mappings, etc.), but **edit rights** for the file itself remain exclusive to the file's holder, following the "Acquire First, Edit Later" principle. Typically, newly tracked files automatically grant ownership to the tracker. +[^export]: Export: The method for transferring asset mappings in JVCS. +[^import]: Import: The method for obtaining asset mappings in JVCS. +[^ref_sheet]: Reference Sheet: A sheet curated by the vault[^vault] administrator, serving as the team's "asset index". +[^vault]: Vault: The asset repository in JVCS where all assets are stored. -### Transferring Files Between Sheets +### 4. Editing Rights Transfer - Through the **Import/Export mechanism** provided by the Sheet System, members can copy a file's **mapping relationship** from one sheet to another. This mechanism transfers the file's **mapping relationship** (i.e., the binding of `VirtualFileId` to a path), not the file entity itself. The file entity always resides in the Virtual File System. This mechanism supports cross-sheet collaboration, such as submitting completed work to the team for sharing, or recommending a file to a specific member for further processing. +The first member to track an asset becomes its initial holder with full editing rights. To transfer rights, the holder releases them, allowing another member to hold the asset. The latest version is synchronized during this process. + + + +> [!NOTE] +> +> This collaboration model manages binary asset structure and versioning, but is not suitable for program development. +> +> Git already serves that purpose well. + + + +## Roadmap + +### Core Library + +- [ ] Incremental file updates and storage +- [ ] Multiple reference sheets + + + +### Extension Tools + +- [ ] Command Line Tool -> [CommandLine](https://github.com/JustEnoughVCS/CommandLine ) (Currently Private) +- [ ] Declarative Asset Management -> [AssetsConfig](https://github.com/JustEnoughVCS/AssetsConfig) (Currently Private) +- [ ] File Merger -> [BinMerger](https://github.com/JustEnoughVCS/BinMerger) (Currently Private) -- **Export**: A member can directly export files from their own sheet to the target sheet's (e.g., Reference Sheet or another member's sheet) pending import area. -- **Import**: The owner of the target sheet receives a list of files pending import. The owner can review and selectively import them (i.e., add the mapping) into their own sheet. During this process, the file's **edit rights remain unchanged**; it simply makes the file "visible" in the recipient's sheet. -This mechanism ensures the **controllability** of file transfer, as the recipient has the right to decide whether to accept the imported file mapping, thereby maintaining the cleanliness and order of their respective workspaces. ## Support -Encountered any issues or have suggestions while using JustEnoughVCS? +Encountered issues or have suggestions while using JustEnoughVCS? + +- Please submit them to https://github.com/JustEnoughVCS/VersionControl/issues, and we'll address your feedback promptly. + +> [!NOTE] +> +> The project is in early development. Instead of creating Issues, we recommend contacting [@Weicao-CatilGrass](https://github.com/Weicao-CatilGrass) directly. +> +> Creating Issues will be more appropriate once basic features are more complete. + -- Please submit them to the https://github.com/JustEnoughVCS/VersionControl/issues page, and we will promptly address your feedback. ## License This project is licensed under the **MIT License**. -For the complete license terms, please refer to the ./LICENSE-MIT.md file in the project root directory. +For complete license terms, see ./LICENSE-MIT.md in the project root. --- -Finally, thank you for your interest in `JustEnoughVCS`! +Thank you for your interest in `JustEnoughVCS`! diff --git a/README_zh_CN.md b/README_zh_CN.md index d391762..9e750e2 100644 --- a/README_zh_CN.md +++ b/README_zh_CN.md @@ -7,7 +7,7 @@ <h1 align="center">JustEnoughVCS</h1> <p align="center"> - 轻量、跨职能、二进制友好的集中式版本控制系统 + 轻量且二进制友好的集中式版本控制系统 </p> <p align="center"> @@ -17,52 +17,68 @@ </p> > [!WARNING] -> JustEnoughVCS 目前正在积极开发中，功能尚不完整 +> JustEnoughVCS 核心功能仍在开发，还不是可使用的状态 > -> 若您对我们的项目感兴趣，推荐直接联系我们。 +> 若您对我们的项目感兴趣，推荐直接联系我们。[联系方式和支持](#支持) - `JustEnoughVCS` 是一个为**跨职能团队**设计的轻量级版本控制系统。它允许每个成员以**最适合其职能角色**的文件结构查看和组织文件，使团队能够专注于内容创作本身。它主要服务于大量二进制资产的协作场景，如**游戏开发**和**多媒体设计**。 -- [虚拟文件系统](#虚拟文件系统) -- [表系统](#表系统) -## 我的设计哲学 - 也是我的拙见 😃 +## 简介 - `JustEnoughVCS` 遵循 "**Just Enough**" 的理念，旨在通过架构设计来实现协作安全。它以**虚拟文件系统**和**表隔离**为核心，为每个创作者提供专注、无干扰的工作空间，让协作变得自然且简单。 +一个文件同时只允许一人修改，这是二进制协作中最不容易出错的范式。JustEnoughVCS 将这种范式通过架构设计简化到极致。你可以随时掌握所关注文件的编辑状态、版本历史等信息。 -## 虚拟文件系统 +### 1. 个人视图 - 虚拟文件系统是 `JustEnoughVCS` 的基础。每个文件由一个全局唯一的 `VirtualFileId` 标识，与其物理路径解耦。它全面记录： +每位成员拥有自己的表[^sheet]，通过表来映射资产内容与目录结构。让每位成员看到的文件结构各不相同，成员只需关注自己工作区中的资产位置，无需担心资产被他人移动，也不会因自己的移动操作影响他人。 -- **所有历史版本** -- **每次修改的描述信息** -- **版本号序列** -- **当前最新版本** -- **当前文件持有者（拥有编辑权限的成员）** +### 2. 资产的 “读” 和 “写” -### 特性 +JustEnoughVCS 的权限模型非常直观：如果你看得见该资产，你就可以读取它；如果你持有该资产，则可以修改它。 -- **可追溯的历史**：轻松查看任何版本的历史并支持回滚。 -- **无冲突协作**：严格遵守 **"先获取，后编辑"** 原则。文件对所有人**可见**但仅对持有者**可写**，从而防止冲突。 -- **获取前验证**：在获取文件之前，本地文件的哈希值和版本号会被严格验证，以确保编辑从最新版本开始。 +[^sheet]: 表（Sheet），成员个人的文件结构，一位成员可以持有多个表，但一个本地工作区[^local_workspace]仅允许同时编辑一个。 +[^local_workspace]: 本地工作区（Local Workspace），资产的本地拷贝目录，用以在成员的本地编辑文件。 -## 表系统 +### 3. 可读性传播 - 表系统充当连接**虚拟文件**与成员**本地工作区**的桥梁。它建立从 `VirtualFileId` 到本地 `SheetPath` 的映射，为每个职能角色（例如，程序员、艺术家、设计师）或个体成员创建定制化的文件视图。 +JustEnoughVCS 中，若您要将资产 **共享给所有人**，需要将该资产的映射导出[^export] 至参照表[^ref_sheet]，由库[^vault]管理员确认后将其公开展示给所有成员。之后所有成员都可以从参照表[^ref_sheet]中导入[^import]该资产的映射，以获取最新的更新。 -表分为两种类型，主要区别在于权限管理： +若您只是需要共享给 **指定的表**，和上述逻辑一致，将资产可见性导出至该表，由该表的持有者确认后，则可以接收到您的文件更新。 -- **参照表 \(Reference Sheet\)**：存储团队间通用的文件，作为共享资源库。所有成员都可以从中获取文件到自己的表中。成员可以将自己的文件提交到参照表，经管理员审核同意后，即可加入参照表中供其他成员导入到自己的表。 -- **成员表 \(Member Sheet\)**：成员自身的表，用来管理个人的工程、项目和素材。成员拥有对**表结构**的完全管理权（如添加、移动映射关系等），但对文件本身的**编辑权**仍由该文件的持有者独占，遵循"先获取，后编辑"的原则。通常，新追踪的文件会自动将其所有权赋予追踪者。 +[^export]: 导出（Export）是 JVCS 中资产映射的传递方式。 +[^import]: 导入（Import）是 JVCS 中获得资产映射的方式。 +[^ref_sheet]: 参照表（Reference Sheet）是由库[^vault]管理员所整理的表，团队中的 ”资产索引“ +[^vault]: 库（Vault）是 JVCS 中的资产仓库，所有的资产存放于此。 -### 表间传递文件 +### 4. 编辑权转移 - 通过表系统提供的 **Import/Export 机制**，成员可以将文件的**映射关系**从一个表传复制到另一个表。此机制传递的是文件的**映射关系**（即 `VirtualFileId` 与路径的绑定），而非文件实体本身。文件实体始终存储在虚拟文件系统中。此机制支持跨表协作，例如将完成的工作成果提交给团队共享，或将文件推荐给特定成员进行后续处理。 +一般来讲，资产的最初持有者是第一个追踪该资产的成员，该成员拥有绝对的资产编辑权。若该成员需要将编辑权转移给其他人，只需 ”放弃“ 编辑权，再由其他成员 ”持有“ ，此过程中会同步资产的最新进度，以确保持有该资产的成员正编辑的资产是最新的。 + + + +> [!NOTE] +> +> 该协作范式解决的是二进制资产的结构和版本管理的问题，不适合作为程序开发的版本控制系统。 +> +> 因为该领域有极为成熟且被认可的 Git。 + + + +## 路线图 + +### 核心库 + +- [ ] 增量的文件更新和存储 +- [ ] 多参照表 + + + +### 拓展工具 + +- [ ] 命令行工具 -> [CommandLine](https://github.com/JustEnoughVCS/CommandLine )（目前 Private） +- [ ] 声明式资产管理 -> [AssetsConfig](https://github.com/JustEnoughVCS/AssetsConfig) (目前 Private) +- [ ] 文件合并器 -> [BinMerger](https://github.com/JustEnoughVCS/BinMerger) (目前 Private) -- **Export（导出）**：成员可以将自己表中的文件直接导出至目标表（如参照表或其他成员的表）的待导入区。 -- **Import（导入）**：目标表的所有者会收到待导入文件的列表。所有者可以查看并选择性地将其导入（即添加映射）到自己的表中。在此过程中，文件的**编辑权保持不变**，仅仅是让文件在接收方的表中"可见"。 -这种机制确保了文件传递的**可控性**，接收方有权决定是否接受导入文件映射，从而维持了各自工作区的整洁与秩序。 ## 支持 @@ -70,6 +86,14 @@ - 请将其提交到 https://github.com/JustEnoughVCS/VersionControl/issues 页面，我们将及时处理您的反馈。 +> [!NOTE] +> +> 当前项目仍在早期开发阶段，比起发起 Issues，我更建议您直接联系仓库维护者 [@Weicao-CatilGrass](https://github.com/Weicao-CatilGrass) +> +> 待基础功能完善后，再发起 Issues 会更加合适 + + + ## 许可证 本项目采用 **MIT 许可证**。 |