diff --git a/CHANGELOG.md b/CHANGELOG.md index 324f753..9b67933 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,24 +1,49 @@ # Changelog +All notable changes to the Git Integration plugin are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## 0.1.4 + +### Fixed + +- **The panel crashed in every project that was not a Git repository.** 0.1.3 announced a "Create Git Repository" view, but the render path behind it was never implemented, so opening a project outside a repository raised `AttributeError`. The view now exists and `git init` runs from it. +- **The panel operated on the wrong folder.** `repo_path` was the Editor process working directory, even though the code comment claimed it preferred the Editor's project root. It now resolves `project_context.get_project_root()` and falls back to the working directory only when no project is loaded. +- **The Window-menu label rendered a raw translation key.** The panel declared a title key that was never present in the translation catalog. The Editor resolves panel titles with `t(title_key)`, which returns the key unchanged when it is missing, so the menu showed the literal key name. +- **Clicking the manual refresh ran an extra unthrottled `git status`.** The refresh button stored a `time.monotonic()` timestamp while the throttle compared against `time.time()`, so the next frame always looked stale. +- **Collapsing headers lost their open state.** The file count was part of the ImGui widget ID, so staging a file reopened the section. + +### Changed + +- The panel UI is localized in English and Simplified Chinese through `package/editor/translations.json`. Every visible string was previously hardcoded English, while the Chinese usage page implied a Chinese UI. +- The commit button reads "Commit", and the menu path is documented as `Extensions/Git Integration`. +- `runtime/` no longer ships the placeholder `Null` component. The plugin is editor-only and exposes no gameplay components. +- The package summary now describes the feature set, and has a localized Chinese variant. + +### Removed + +- The unused `files_status_list` state left over from the status refactor. + +### Documentation + +- The README, changelog, and in-editor usage pages were rewritten to match the code. The Chinese README no longer carried the "plugin template" title. +- Added `ROADMAP.md`, `CONTRIBUTING.md`, and `RELEASING.md`. + ## 0.1.3 +> The "Create Git Repository" view announced below was not wired up in this version. It was completed in 0.1.4. + ### Added -- Repository detection via `git rev-parse --is-inside-work-tree`; the panel now renders a dedicated "Create Git Repository" view when the project is not yet a Git repository. + +- Repository detection via `git rev-parse --is-inside-work-tree`; the panel renders a dedicated "Create Git Repository" view when the project is not yet a Git repository. - One-click repository initialization (`git init`) directly from the panel. - VS Code-style staging: a per-file `+` button in the Changes list, plus a "Stage all" action. - Unstaging via a per-file `-` button, including support for repositories with no commits yet. - Commit workflow with a persistent message buffer, empty-message validation, and immediate status refresh after commit. - Manual refresh button to force `git status` without waiting for the throttle interval. - Files with dual status (e.g. `AM`) are now shown in both "Staged Changes" and "Changes", matching `git status` behavior. -### Planned -- Branch display and switching. -- File status coloring (Modified / Added / Deleted / Untracked). -- Discard changes action for unstaged files. -- Push / Pull controls. -- Diff preview for tracked files. -- Asynchronous `git status` execution to keep the editor responsive on large repositories. ### Fixed + - Engine crash caused by calling `subprocess` synchronously from `on_enable`; Git detection is now performed lazily during the first render. - `exit status 128` when `git status` was executed outside a repository or in the wrong working directory. - Duplicate ImGui item IDs (`duplicate visible item ID`) caused by repeated `+` / `-` button labels inside loops. @@ -27,6 +52,7 @@ - "Stage all" button not responding due to overlapping with the collapsing header's hit area. ### Changed + - Working directory is now always passed explicitly via `cwd=` to every Git subprocess. - `files_status_list` replaced with three independent collections (`staged_files`, `unstaged_files`, `untracked_files`), allowing a single file to appear in multiple states simultaneously. - Status parsing now uses `git status --porcelain` and updates the lists atomically, preserving the last known state on transient failures. @@ -34,4 +60,6 @@ ## 0.1.2 -- Refactor example plugin name. +### Changed + +- Replaced the example plugin name with the real name. diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md index 97a77c5..82e5156 100644 --- a/CHANGELOG.zh-CN.md +++ b/CHANGELOG.zh-CN.md @@ -1,8 +1,39 @@ # 更新日志 +Git 集成插件的所有重要变更都记录在本文件中。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。 + +## 0.1.4 + +### 修复 + +- **项目文件夹不是 Git 仓库时面板直接崩溃。** 0.1.3 声称加入了「创建 Git 仓库」界面,但背后的渲染路径从未实现,打开非仓库项目会抛出 `AttributeError`。现在该界面已实现,并可在其中执行 `git init`。 +- **面板作用在了错误的目录上。** `repo_path` 之前是 Editor 进程的工作目录,尽管代码注释写着「优先从引擎获取项目根」。现在改为解析 `project_context.get_project_root()`,只有在没有打开项目时才回退到工作目录。 +- **窗口菜单里显示的是原始翻译键名。** 面板声明了一个翻译目录里根本不存在的标题键,而编辑器用 `t(title_key)` 解析面板标题,查不到时原样返回键名,于是菜单里直接显示了键名字符串。 +- **点击手动刷新会多跑一次未节流的 `git status`。** 刷新按钮记录的是 `time.monotonic()` 时间戳,而节流比较用的是 `time.time()`,导致下一帧总是判定为「已过期」。 +- **折叠标题会丢失展开状态。** 文件数量被编进了 ImGui 控件 ID,暂存一个文件就会让该区块重新展开。 + +### 变更 + +- 面板界面通过 `package/editor/translations.json` 支持英文与简体中文。此前所有可见文案都是硬编码英文,而中文使用页却暗示有中文界面。 +- 提交按钮文案为「提交」,菜单路径文档统一为 `Extensions/Git Integration`。 +- `runtime/` 不再附带占位的 `Null` 组件。本插件仅在编辑器中使用,不提供任何游戏运行时组件。 +- 包简介改为描述实际功能集,并新增了中文本地化简介。 + +### 移除 + +- 状态重构后遗留的未使用状态 `files_status_list`。 + +### 文档 + +- README、更新日志与编辑器内使用页全部重写,与代码保持一致。中文 README 不再使用「插件模板」这一标题。 +- 新增 `ROADMAP.md`、`CONTRIBUTING.md` 与 `RELEASING.md`。 + ## 0.1.3 +> 下方提到的「创建 Git 仓库」界面在本版本中并未接通,实际是在 0.1.4 才完成的。 + ### 新增 + - 使用 `git rev-parse --is-inside-work-tree` 检测仓库;项目尚未初始化 Git 时,面板会显示独立的「创建 Git 仓库」界面。 - 可在面板中一键初始化仓库(`git init`)。 - 仿 VS Code 的暂存操作:Changes 列表每个文件右侧提供 `+` 按钮,并提供「Stage all」整体暂存。 @@ -10,15 +41,9 @@ - 提交流程:持久化提交消息缓冲区、空消息校验,以及提交后立即刷新状态。 - 手动刷新按钮,可绕过节流间隔强制执行 `git status`。 - 双状态文件(如 `AM`)现在会同时出现在「Staged Changes」与「Changes」中,与 `git status` 的行为一致。 -### 计划 -- 分支显示与切换。 -- 文件状态着色(Modified / Added / Deleted / Untracked)。 -- 未暂存文件的「放弃更改」(Discard changes)操作。 -- Push / Pull 控制。 -- 已跟踪文件的 Diff 预览。 -- 异步执行 `git status`,在大仓库中保持编辑器响应。 ### 修复 + - 在 `on_enable` 中同步调用 `subprocess` 导致引擎崩溃;Git 探测改为首次渲染时惰性执行。 - 在仓库外或错误工作目录中执行 `git status` 时返回 `exit status 128`。 - 循环内 `+` / `-` 按钮标签重复导致的 ImGui ID 冲突(`duplicate visible item ID`)。 @@ -27,6 +52,7 @@ - 「Stage all」按钮与折叠标题点击区域重叠导致无响应。 ### 变更 + - 所有 Git 子进程调用现在都通过 `cwd=` 显式指定工作目录。 - 以 `staged_files`、`unstaged_files`、`untracked_files` 三个独立集合取代 `files_status_list`,允许同一文件同时处于多个状态。 - 状态解析改用 `git status --porcelain`,并以原子方式更新列表;临时失败时保留上一次的已知状态。 @@ -34,4 +60,6 @@ ## 0.1.2 -- 重建插件引擎实例名称。 +### 变更 + +- 将示例名称替换为真实名称。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..108eef5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing + +Thanks for helping improve the Git Integration plugin. + +## Getting set up + +The project has no third-party dependencies — the Python standard library is enough. + +```bash +git clone git@github.com:Wokrlie/InxGitIntegration.git +cd InxGitIntegration +python .infernux-dev/validate.py +python -m unittest discover -s tests +``` + +## Branches + +- `main` — released code. Every commit here has passed CI. +- `dev` — the integration branch. Feature work lands here through a pull request. + +## Commit messages + +Use a short imperative subject line, optionally with a conventional-commit prefix: + +``` +feat: add branch switching to the panel +fix: keep the commit message buffer across renders +docs: align the usage page with the panel layout +``` + +The prefix set is `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `build`, `ci`. + +## Before you open a pull request + +Run the checks that CI runs: + +```bash +python .infernux-dev/validate.py +python -m unittest discover -s tests +python package.py build dist/plugin.inxpkg && python package.py verify dist/plugin.inxpkg +``` + +## Documentation rules + +- Every English page under `package/plugin_pages/` needs a matching `.zh-CN.md` file. The validator rejects the package otherwise. +- Keep the two languages in sync — a change to `usage.md` needs the same change to `usage.zh-CN.md`. +- User-visible strings belong in `package/editor/translations.json`, not inline in the panel. Both locales must declare the same key set, and every key must be namespaced under `wokrlie.git_integration.`. +- Record new work under an `## Unreleased` heading in both `CHANGELOG.md` and `CHANGELOG.zh-CN.md`. + +## Code conventions + +- The Editor half of the plugin lives in `package/editor/`, the player-facing half in `package/runtime/`. Runtime code must not import Editor modules; the validator enforces that boundary. +- Every `git` call must pass `cwd=` explicitly so the panel always operates on the folder open in the Editor. +- Use `subprocess.run` with a timeout. The render thread must never block indefinitely. +- Panel state that survives a render lives on the instance; it is never stored in a module-level global. diff --git a/LICENSE b/LICENSE index c0bacf5..a74e507 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2026 Plugin Authors +Copyright (c) 2026 Wokrlie Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index c2c0643..4b2808c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,89 @@ # Infernux Git Integration -This repository for integrating git managing for Infernux Engine. +A source control panel for the [Infernux Engine](https://github.com/ChenlizheMe/Infernux). Stage, unstage, and commit straight from the editor — no terminal required. -[简体中文](README.zh-CN.md) · [Infernux Engine](https://github.com/ChenlizheMe/Infernux) +[简体中文](README.zh-CN.md) · [Infernux Engine](https://github.com/ChenlizheMe/Infernux) · [Plugin development docs](https://github.com/ChenlizheMe/Infernux/tree/master/docs) + +[![Validate and Release Plugin](https://github.com/Wokrlie/InxGitIntegration/actions/workflows/validate.yml/badge.svg)](https://github.com/Wokrlie/InxGitIntegration/actions/workflows/validate.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +## Features + +- One-click `git init` when the open project folder is not a repository yet. +- VS Code-style staging: a `+` button per file, plus **Stage all** (equivalent to `git add -A`). +- Unstaging with a `−` button per file, including in repositories that have no commits yet. +- Commit flow with a persistent message buffer and empty-message validation. +- Automatic refresh of the file lists, plus a manual refresh button. +- Files with a dual status (for example `AM`) appear in both lists, matching `git status`. +- Localized panel UI in English and Simplified Chinese. + +## Requirements + +| Requirement | Version | +| --- | --- | +| Infernux Engine | `>=0.4.1,<0.5` | +| Git | A recent version available on your `PATH` | + +Git is a **runtime requirement**. The panel shells out to the `git` executable; when it is missing, the panel shows a short notice instead of the file lists. + +## Installation + +### From a release + +1. Download `wokrlie.git_integration.inxpkg` from the [Releases page](https://github.com/Wokrlie/InxGitIntegration/releases). +2. In the Editor, open `Extensions/Plugins` and install the downloaded archive. + +The Editor checks the archive against the engine version declared in `package/inx_package.json` and refuses to install an incompatible build. + +### From source + +```bash +python package.py build dist/wokrlie.git_integration.inxpkg +``` + +The build is deterministic — two runs over the same source produce byte-identical archives. + +## Usage + +Open `Extensions/Git Integration` in the menu bar. The panel acts on the project folder currently open in the editor. + +The full walkthrough lives in [`package/plugin_pages/usage.md`](package/plugin_pages/usage.md), which also ships inside the package as the in-editor usage page. + +## Troubleshooting + +**The panel reports that Git is not usable.** Git is not installed, or the Editor was started with a `PATH` that does not include it. Install Git and restart the Editor. + +**Commit does nothing.** The commit message box is empty. Enter a message first. + +**`git commit` fails asking who you are.** Git has no identity configured. Run: + +```bash +git config --global user.name "Your Name" +git config --global user.email "you@example.com" +``` + +**The panel shows files you did not expect.** The panel follows the folder open in the Editor, not the folder the Editor binary lives in. + +## Development + +```bash +python .infernux-dev/validate.py # package layout and Python sources +python -m unittest discover -s tests # validation and release contracts +python package.py build dist/plugin.inxpkg # deterministic build +python package.py verify dist/plugin.inxpkg # verify a built archive +``` + +The Editor-only code lives in `package/editor/`, and the runtime surface in `package/runtime/`. `package/plugin_pages/` holds the in-editor documentation, and every English page must have a matching `.zh-CN.md` sibling — the validator enforces this. + +## Documentation + +| Document | Purpose | +| --- | --- | +| [package/plugin_pages/usage.md](package/plugin_pages/usage.md) | In-editor usage guide (English) | +| [package/plugin_pages/usage.zh-CN.md](package/plugin_pages/usage.zh-CN.md) | In-editor usage guide (Simplified Chinese) | +| [ROADMAP.md](ROADMAP.md) | Planned features | +| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution and commit conventions | +| [RELEASING.md](RELEASING.md) | Release procedure | ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index 0562b96..0231ea5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,9 +1,90 @@ -# Infernux 插件模板 +# Infernux Git 集成 -这是 [Infernux](https://github.com/ChenlizheMe/Infernux) 引擎的一个版本管理简单集成。 +[Infernux 引擎](https://github.com/ChenlizheMe/Infernux)的版本管理面板。直接在编辑器里完成暂存、取消暂存和提交——不用切到终端。 [English](README.md) · [Infernux 引擎](https://github.com/ChenlizheMe/Infernux) · [插件开发文档](https://github.com/ChenlizheMe/Infernux/tree/master/docs) · [官方插件](https://github.com/ChenlizheMe/Infernux#plugins) +[![Validate and Release Plugin](https://github.com/Wokrlie/InxGitIntegration/actions/workflows/validate.yml/badge.svg)](https://github.com/Wokrlie/InxGitIntegration/actions/workflows/validate.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +## 功能 + +- 项目文件夹还不是仓库时,可一键执行 `git init`。 +- 仿 VS Code 的暂存操作:每个文件右侧一个 `+` 按钮,外加**暂存全部**(等价于 `git add -A`)。 +- 逐个文件取消暂存(`−` 按钮),仓库还没有任何提交时同样可用。 +- 提交流程:消息缓冲区持久保留,空消息会被拦截。 +- 文件列表自动刷新,并提供手动刷新按钮。 +- 双状态文件(例如 `AM`)会同时出现在两个列表中,与 `git status` 的行为一致。 +- 面板界面支持英文与简体中文。 + +## 环境要求 + +| 依赖 | 版本 | +| --- | --- | +| Infernux 引擎 | `>=0.4.1,<0.5` | +| Git | `PATH` 中可用的较新版本 | + +Git 是**运行时依赖**。面板通过 `git` 可执行文件完成所有操作;Git 缺失时,面板会显示一条简短提示而不是文件列表。 + +## 安装 + +### 从发布页安装 + +1. 从 [Releases 页面](https://github.com/Wokrlie/InxGitIntegration/releases)下载 `wokrlie.git_integration.inxpkg`。 +2. 在编辑器中打开 `扩展/插件`,安装下载的归档文件。 + +编辑器会对照 `package/inx_package.json` 中声明的引擎版本检查归档文件,并拒绝安装不兼容的版本。 + +### 从源码构建 + +```bash +python package.py build dist/wokrlie.git_integration.inxpkg +``` + +构建是确定性的——同一份源码构建两次会得到字节完全相同的归档文件。 + +## 使用 + +在菜单栏打开 `扩展/Git 集成`。面板作用于编辑器中当前打开的项目文件夹。 + +完整说明见 [`package/plugin_pages/usage.zh-CN.md`](package/plugin_pages/usage.zh-CN.md),该文件也会随包发布,成为编辑器内的使用页。 + +## 故障排查 + +**面板提示当前环境无法使用 Git。** 系统没有安装 Git,或者 Editor 启动时的 `PATH` 里找不到它。安装 Git 后重启 Editor。 + +**点击提交没有任何反应。** 提交信息为空,需要先填写。 + +**`git commit` 报错询问你的身份。** Git 还没有配置用户信息,执行: + +```bash +git config --global user.name "你的名字" +git config --global user.email "you@example.com" +``` + +**面板显示了预期之外的文件。** 面板跟随的是编辑器中打开的文件夹,而不是 Editor 程序所在的目录。 + +## 本地开发 + +```bash +python .infernux-dev/validate.py # 检查包布局与 Python 源码 +python -m unittest discover -s tests # 校验与发布相关的契约测试 +python package.py build dist/plugin.inxpkg # 确定性构建 +python package.py verify dist/plugin.inxpkg # 校验构建产物 +``` + +仅编辑器使用的代码位于 `package/editor/`,运行时接口位于 `package/runtime/`。`package/plugin_pages/` 存放编辑器内文档,每个英文页面都必须有对应的 `.zh-CN.md`——校验器会强制检查这一点。 + +## 文档 + +| 文档 | 用途 | +| --- | --- | +| [package/plugin_pages/usage.md](package/plugin_pages/usage.md) | 编辑器内使用说明(英文) | +| [package/plugin_pages/usage.zh-CN.md](package/plugin_pages/usage.zh-CN.md) | 编辑器内使用说明(简体中文) | +| [ROADMAP.md](ROADMAP.md) | 后续计划 | +| [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献与提交规范 | +| [RELEASING.md](RELEASING.md) | 发布流程 | + ## 许可证 [MIT](LICENSE)。 diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..e909cf9 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,50 @@ +# Releasing + +Releases are produced by GitHub Actions. No artifact is uploaded by hand. + +## Sources of truth + +| What | Where | +| --- | --- | +| Plugin version | `package/inx_package.json` → `version` | +| Engine compatibility | `package/inx_package.json` → `engine` | +| Release notes | `CHANGELOG.md` and `CHANGELOG.zh-CN.md` | + +The release tag must match the manifest version exactly — `v0.1.4` for version `0.1.4`. `package.py release-manifest` fails on any mismatch, so a mistyped tag stops the release instead of publishing a mislabelled archive. + +## Procedure + +1. Update `CHANGELOG.md` and `CHANGELOG.zh-CN.md`, and set the new version in `package/inx_package.json`. +2. Merge the change into `main` and wait for the `Validate and Release Plugin` workflow to go green on `main`. +3. Tag the merge commit and push the tag: + + ```bash + git tag v0.1.4 + git push origin v0.1.4 + ``` + +4. The `release` job runs on the tag. It builds the archive, verifies it, checks that two independent builds are byte-identical, generates `infernux-plugin-release.json`, and publishes both files as GitHub Release assets. + +## Published releases are immutable + +A `reference` / `version` pair is a permanent identifier. Once a release exists, republishing the same version must fail rather than replace the archive that users have already installed. + +The workflow enforces this by letting `gh release create` fail on a duplicate tag. `tests/test_release_immutability.py` runs the real publish step against a stub `gh` to prove that a duplicate release leaves both existing assets untouched. + +Because of this, a fix for a published version needs a **new** version number. Never re-cut an existing tag. + +## Artifact names + +- Archive: `wokrlie.git_integration.inxpkg` — the manifest `reference` with `/` replaced by `.`. +- Release manifest: `infernux-plugin-release.json`. + +## Verifying a release locally + +```bash +python package.py build dist/wokrlie.git_integration.inxpkg +python package.py verify dist/wokrlie.git_integration.inxpkg +python package.py release-manifest dist/wokrlie.git_integration.inxpkg \ + --tag v0.1.4 --output dist/infernux-plugin-release.json +``` + +The build is deterministic: running it twice over the same source must produce byte-identical archives, which is what CI asserts before it publishes anything. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..a7b7d34 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,18 @@ +# Roadmap + +Planned work for the Git Integration plugin. Delivered changes are recorded in [CHANGELOG.md](CHANGELOG.md) and [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md). + +## Next + +- **Branch display and switching** — show the current branch, and let the user switch or create branches from the panel. +- **File status coloring** — distinguish Modified / Added / Deleted / Untracked entries in both file lists. +- **Discard changes** — revert the unstaged modifications of a single file. +- **Push / Pull controls** — fetch, pull, and push without leaving the Editor. +- **Diff preview** — show the content diff of a tracked file. +- **Asynchronous `git status`** — move status collection off the render thread so large repositories do not stall the Editor. + +## Notes + +Every item above has to keep the render thread responsive. The panel currently shells out to `git` synchronously during rendering, with a one-second throttle between refreshes. Asynchronous status collection is listed last because it is the change that makes the rest cheap to add: once status collection no longer blocks the frame, per-file operations can follow the same pattern. + +Adding an item to this file is welcome — open a pull request that describes the user problem it solves, not just the API it would use. diff --git a/package/editor/translations.json b/package/editor/translations.json index 6fb97a9..afe35ad 100644 --- a/package/editor/translations.json +++ b/package/editor/translations.json @@ -3,11 +3,33 @@ "locales": { "en": { "wokrlie.git_integration.menu_root": "Git Integration", - "wokrlie.git_integration.panel_title": "Git Integration" + "wokrlie.git_integration.panel_title": "Git Integration", + "wokrlie.git_integration.source_control": "Source Control", + "wokrlie.git_integration.staged_changes": "Staged Changes", + "wokrlie.git_integration.changes": "Changes", + "wokrlie.git_integration.stage_all": "Stage all", + "wokrlie.git_integration.none": "(none)", + "wokrlie.git_integration.commit_message": "Commit message:", + "wokrlie.git_integration.commit": "Commit", + "wokrlie.git_integration.create_repository": "Create Git Repository", + "wokrlie.git_integration.not_a_repository": "This folder is not a Git repository yet.", + "wokrlie.git_integration.repository_folder": "Repository folder", + "wokrlie.git_integration.git_unavailable": "Git is not usable in the current environment." }, "zh": { - "wokrlie.git_integration.menu_root": "Git集成", - "wokrlie.git_integration.panel_title": "Git集成" + "wokrlie.git_integration.menu_root": "Git 集成", + "wokrlie.git_integration.panel_title": "Git 集成", + "wokrlie.git_integration.source_control": "源代码管理", + "wokrlie.git_integration.staged_changes": "已暂存的更改", + "wokrlie.git_integration.changes": "更改", + "wokrlie.git_integration.stage_all": "暂存全部", + "wokrlie.git_integration.none": "(无)", + "wokrlie.git_integration.commit_message": "提交信息:", + "wokrlie.git_integration.commit": "提交", + "wokrlie.git_integration.create_repository": "创建 Git 仓库", + "wokrlie.git_integration.not_a_repository": "当前文件夹还不是 Git 仓库。", + "wokrlie.git_integration.repository_folder": "仓库目录", + "wokrlie.git_integration.git_unavailable": "当前环境无法使用 Git。" } } } diff --git a/package/editor/wokrlie/git_integration/panel.py b/package/editor/wokrlie/git_integration/panel.py index 8a08c67..d731e71 100644 --- a/package/editor/wokrlie/git_integration/panel.py +++ b/package/editor/wokrlie/git_integration/panel.py @@ -1,15 +1,23 @@ -"""Example panel available only inside the editor.""" +"""Git panel available only inside the editor.""" +from __future__ import annotations + +import os +import subprocess +import time + +from infernux import Debug +from infernux.engine.i18n import t from infernux.engine.interaction import PanelInteractionDescriptor +from infernux.engine.project_context import get_project_root from infernux.engine.ui.editor_panel import EditorPanel from infernux.engine.ui.panel_registry import editor_panel -from infernux import Debug -import subprocess, time, os + @editor_panel( - "Git integration", + "Git Integration", type_id="wokrlie.git_integration", - title_key="wokrlie.git_panel", + title_key="wokrlie.git_integration.panel_title", menu_path="Extensions/Git Integration", menu_path_keys=( "menu.extensions", @@ -17,24 +25,27 @@ ), interaction=PanelInteractionDescriptor(), ) - - class GitIntegrationPanel(EditorPanel): + """Source control panel backed by the ``git`` command line.""" + def __init__(self) -> None: super().__init__("Git Integration", "wokrlie.git_integration.panel") self.have_git: bool = False self.is_repo_initialized: bool = False - self.files_status_list: dict[str, str] = {} + + # ``staged_files``/``unstaged_files`` map a path to its porcelain status + # code. A path may appear in both when it has staged *and* unstaged + # content (for example the ``AM`` state). + self.staged_files: dict[str, str] = {} + self.unstaged_files: dict[str, str] = {} + self.untracked_files: list[str] = [] self._commit_message: str = "" self._last_refresh: float = 0.0 self._refresh_interval: float = 1.0 self._git_checked: bool = False - # 项目根目录,优先从引擎获取,否则回退到当前工作目录 - self.repo_path: str = os.getcwd() - # ------------------------------------------------------------------ # # 生命周期(保持惰性初始化,避免 on_enable 崩溃) # ------------------------------------------------------------------ # @@ -42,6 +53,19 @@ def on_enable(self) -> None: self._git_checked = False self.have_git = False self.is_repo_initialized = False + self.staged_files = {} + self.unstaged_files = {} + self.untracked_files = [] + + @property + def repo_path(self) -> str: + """The folder the panel operates on. + + Prefers the project root the Editor currently has open and falls back + to the process working directory when no project is loaded. Resolved on + every read so switching projects does not leave a stale path behind. + """ + return get_project_root() or os.getcwd() def on_render_content(self, ctx) -> None: if not self._git_checked: @@ -49,7 +73,7 @@ def on_render_content(self, ctx) -> None: self._git_checked = True if not self.have_git: - ctx.label("Git is not usable in current environment.") + ctx.label(t("wokrlie.git_integration.git_unavailable")) return # 节流刷新仓库状态 @@ -58,16 +82,27 @@ def on_render_content(self, ctx) -> None: self.refresh_git_status() self._last_refresh = now - # ==================== 分支渲染 ==================== if not self.is_repo_initialized: self._render_no_repo_ui(ctx) # 未初始化仓库:只显示创建按钮 return self._render_git_ui(ctx) # 已初始化仓库:正常 Git 操作界面 - # =================================================== + + def _render_no_repo_ui(self, ctx) -> None: + """Render the view shown when the folder is not a Git repository yet.""" + ctx.label(t("wokrlie.git_integration.not_a_repository")) + ctx.button( + f"{t('wokrlie.git_integration.create_repository')}##create_repository", + self.init_git_repo, + 240.0, + 28.0, + ) + ctx.label( + f"{t('wokrlie.git_integration.repository_folder')}: {self.repo_path}" + ) def _render_git_ui(self, ctx) -> None: - ctx.label("Source Control") + ctx.label(t("wokrlie.git_integration.source_control")) ctx.same_line() ctx.button("⟳##refresh_git", self._manual_refresh, 28.0, 20.0) @@ -77,8 +112,8 @@ def _render_git_ui(self, ctx) -> None: self._render_changes_section(ctx) # -------- 提交消息 -------- - ctx.label("Commit message:") - self._try_set_next_item_width(ctx, 380.0) + ctx.label(t("wokrlie.git_integration.commit_message")) + ctx.set_next_item_width(380.0) self._commit_message = ctx.text_input( label="##commit_msg", value=self._commit_message, # ← 持久状态,不再用提示字面量 @@ -87,7 +122,7 @@ def _render_git_ui(self, ctx) -> None: # -------- 提交按钮 -------- commit_msg = self._commit_message ctx.button( - "Check in staged changes", + t("wokrlie.git_integration.commit"), lambda: self.check_in_staged_changes(commit_msg), 380.0, # ← 加宽,避免文字被截断 30.0, @@ -95,22 +130,16 @@ def _render_git_ui(self, ctx) -> None: finally: ctx.end_group() - - def _try_set_next_item_width(self, ctx, width: float) -> None: - """ImGui 的 SetNextItemWidth 若已绑定则使用,否则降级为默认宽度。""" - try: - ctx.set_next_item_width(width) - except (AttributeError, TypeError): - pass - - def _render_staged_section(self, ctx) -> None: - expanded = ctx.collapsing_header(f"Staged Changes ({len(self.staged_files)})") + expanded = ctx.collapsing_header( + f"{t('wokrlie.git_integration.staged_changes')} " + f"({len(self.staged_files)})###staged_changes" + ) if not expanded: return if not self.staged_files: - ctx.label(" (none)") + ctx.label(f" {t('wokrlie.git_integration.none')}") return for path, status in sorted(self.staged_files.items()): @@ -123,15 +152,16 @@ def _render_staged_section(self, ctx) -> None: 18.0, ) - def _render_changes_section(self, ctx) -> None: total = len(self.unstaged_files) + len(self.untracked_files) - expanded = ctx.collapsing_header(f"Changes ({total})") + expanded = ctx.collapsing_header( + f"{t('wokrlie.git_integration.changes')} ({total})###changes" + ) # Stage all 放到 header 下一行,避免 same_line 遮挡点击区域 if total > 0: ctx.button( - "Stage all##stage_all", + f"{t('wokrlie.git_integration.stage_all')}##stage_all", self.stage_all, 120.0, 22.0, @@ -141,7 +171,7 @@ def _render_changes_section(self, ctx) -> None: return if total == 0: - ctx.label(" (none)") + ctx.label(f" {t('wokrlie.git_integration.none')}") return for path, status in sorted(self.unstaged_files.items()): @@ -264,12 +294,17 @@ def _is_inside_work_tree(self) -> bool: # ------------------------------------------------------------------ # def init_git_repo(self) -> None: """在当前项目目录初始化一个新的 Git 仓库。""" + folder = self.repo_path + if not os.path.isdir(folder): + Debug.error(f"Cannot initialise a repository in a missing folder: {folder}") + return + try: result = subprocess.run( ["git", "init"], capture_output=True, text=True, - cwd=self.repo_path, + cwd=folder, timeout=10, ) except FileNotFoundError: @@ -344,7 +379,6 @@ def stage_file(self, path: str) -> None: else: Debug.error(f"`git add {path}` failed: {result.stderr.strip()}") - def stage_all(self) -> None: """暂存所有变更(等价于 `git add -A`,包含修改、新增和删除)。""" if not self.is_repo_initialized: @@ -368,7 +402,6 @@ def stage_all(self) -> None: else: Debug.error(f"`git add -A` failed: {result.stderr.strip()}") - def unstage_file(self, path: str) -> None: if not self.is_repo_initialized: return @@ -394,7 +427,9 @@ def unstage_file(self, path: str) -> None: else: Debug.error(f"unstage failed: {fallback.stderr.strip()}") - + # ------------------------------------------------------------------ # + # 刷新辅助 + # ------------------------------------------------------------------ # def _refresh_after_mutation(self) -> None: """任何 stage/unstage/commit 之后调用,立即刷新状态并重置节流计时。""" self.refresh_git_status() @@ -402,4 +437,4 @@ def _refresh_after_mutation(self) -> None: def _manual_refresh(self) -> None: self.refresh_git_status() - self._last_refresh = time.monotonic() \ No newline at end of file + self._last_refresh = time.time() diff --git a/package/inx_package.json b/package/inx_package.json index a97e614..b0d98b4 100644 --- a/package/inx_package.json +++ b/package/inx_package.json @@ -2,7 +2,10 @@ "$schema": "infernux.inxpackage.source", "reference": "wokrlie/git_integration", "name": "Git Integration", - "version": "0.1.3", + "version": "0.1.4", "engine": ">=0.4.1,<0.5", - "intro": "A simple git integration for infernux engine" + "intro": "Git source control for the Infernux Engine: stage, unstage, and commit straight from the editor.", + "intros": { + "zh-CN": "Infernux 引擎的 Git 源代码管理面板:直接在编辑器里暂存、取消暂存和提交。" + } } diff --git a/package/plugin_pages/usage.md b/package/plugin_pages/usage.md index 351c1ca..de048c0 100644 --- a/package/plugin_pages/usage.md +++ b/package/plugin_pages/usage.md @@ -1,39 +1,56 @@ # Git Panel The Git panel lets you stage, unstage, and commit changes from inside the Infernux editor, without switching to a terminal. + ## Opening the panel -You can find it in the menu bar: `Extensions/ GitIntegration` + +You can find it in the menu bar: `Extensions/Git Integration`. + ## Before you start -The panel works on the project folder currently open in the editor. If that folder is not a Git repository yet, the panel shows a Create Git Repository view instead of the normal layout. Click Create Git Repository to run git init on the project folder; the panel then switches to the normal view. -The panel layout +The panel works on the project folder currently open in the editor. If that folder is not a Git repository yet, the panel shows a **Create Git Repository** view instead of the normal layout. Click **Create Git Repository** to run `git init` on the project folder; the panel then switches to the normal view. -The normal view has three parts, from top to bottom: +Git must be installed and reachable on your `PATH`. When it is not, the panel shows a short notice instead of the file lists. - - Staged Changes — files that will be included in the next commit. - - Changes — files that have been modified or deleted but are not staged yet. - - Commit area — a message box, a Commit button, and a Refresh button. +## The panel layout + +The normal view has four parts, from top to bottom: + +- **Source Control** — the header. The `⟳` button on the right forces an immediate `git status`, skipping the refresh interval. +- **Staged Changes** — files that will be included in the next commit. +- **Changes** — files that have been modified or deleted but are not staged yet, plus untracked files. +- **Commit area** — a message box and a **Commit** button. A file can appear in both lists at once. For example, a file that was staged and then modified again shows up under Staged Changes and under Changes, so you can tell it has both staged and unstaged content. ## Staging and unstaging - - To stage a single file, click the + button on its row in Changes. - - To stage everything in Changes at once, click Stage all. - - To unstage a file, click the − button on its row in Staged Changes. This also works in a repository that has no commits yet. +- To stage a single file, click the `+` button on its row in **Changes**. +- To stage everything in **Changes** at once, click **Stage all**. +- To unstage a file, click the `−` button on its row in **Staged Changes**. This also works in a repository that has no commits yet. + +**Stage all** is equivalent to `git add -A`: it stages modifications, additions, and deletions. ## Committing - - Type a message into the message box. The text stays there while you keep working in the panel. +- Type a message into the message box. The text stays there while you keep working in the panel. +- Click **Commit**. The commit is created and the file lists refresh right away. +- If the message box is empty, the commit button does nothing — enter a message first. - - Click Commit. The commit is created and the file lists refresh right away. +## Refreshing the file lists - - If the message box is empty, the commit button does nothing — enter a message first. +The panel updates the file lists automatically, at most once per second. If you want to see the current state immediately — for example after running Git commands in a terminal — click the `⟳` button in the header. -## Refreshing the file lists +## Troubleshooting + +**The panel reports that Git is not usable.** Git is not installed, or it is not on the `PATH` the Editor was started with. Install Git and restart the Editor. + +**Commit does nothing.** The message box is empty. Enter a commit message first. + +**`git commit` fails asking who you are.** Git has no identity configured. Run `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"`. -The panel updates the file lists automatically. If you want to see the current state immediately — for example after running Git commands in a terminal — click Refresh. +**A new file never leaves Changes.** Untracked files are marked `?` until they are staged. ## Upcoming features -Branch display and switching, file status coloring, discard-changes for unstaged files, Push/Pull controls, and diff preview are planned for future versions. \ No newline at end of file +Branch display and switching, file status coloring, discard-changes for unstaged files, Push/Pull controls, diff preview, and asynchronous `git status` execution are planned for future versions. diff --git a/package/plugin_pages/usage.zh-CN.md b/package/plugin_pages/usage.zh-CN.md index b1978ce..d4bec36 100644 --- a/package/plugin_pages/usage.zh-CN.md +++ b/package/plugin_pages/usage.zh-CN.md @@ -1,41 +1,56 @@ # Git 面板 Git 面板让你直接在 Infernux 编辑器里完成暂存、取消暂存和提交,不用切到终端。 + ## 打开面板 -你可以再菜单栏的`插件/Git集成` -# 开始之前 -面板作用于当前在编辑器中打开的项目文件夹。如果这个文件夹还不是 Git 仓库,面板不会显示正常界面,而是显示 Create Git Repository 视图。点击 Create Git Repository 会对项目文件夹执行 git init,之后面板自动切换到正常界面。 -## 面板结构 +你可以在菜单栏的 `扩展/Git 集成` 找到它。 -正常界面从上到下分三部分: +## 开始之前 - - Staged Changes —— 下次提交会包含的文件。 +面板作用于当前在编辑器中打开的项目文件夹。如果这个文件夹还不是 Git 仓库,面板不会显示正常界面,而是显示「创建 Git 仓库」视图。点击**创建 Git 仓库**会对项目文件夹执行 `git init`,之后面板自动切换到正常界面。 - - Changes —— 已修改或删除、但还没暂存的文件。 +系统必须已安装 Git,并且 Editor 启动时能在 `PATH` 中找到它。否则面板不会显示文件列表,而会显示一条简短提示。 - - 提交区 —— 消息输入框、Commit 按钮和 Refresh 按钮。 +## 面板结构 -一个文件可以同时出现在两个列表里。例如某个文件暂存之后又被修改,它会同时显示在 Staged Changes 和 Changes 中,这样你能看出它既有已暂存的内容,也有未暂存的改动。 -暂存与取消暂存 +正常界面从上到下分四部分: - - 暂存单个文件:点击 Changes 中该文件右侧的 + 按钮。 +- **源代码管理** —— 标题栏。右侧的 `⟳` 按钮会立即执行一次 `git status`,跳过刷新间隔。 +- **已暂存的更改** —— 下次提交会包含的文件。 +- **更改** —— 已修改或删除、但还没暂存的文件,以及未跟踪的文件。 +- **提交区** —— 消息输入框和**提交**按钮。 - - 一次性暂存 Changes 里的全部文件:点击 Stage all。 +一个文件可以同时出现在两个列表里。例如某个文件暂存之后又被修改,它会同时显示在「已暂存的更改」和「更改」中,这样你能看出它既有已暂存的内容,也有未暂存的改动。 - - 取消暂存:点击 Staged Changes 中该文件右侧的 − 按钮。仓库还没有任何提交时,这个操作同样可用。 +## 暂存与取消暂存 -## 提交 +- 暂存单个文件:点击「更改」中该文件右侧的 `+` 按钮。 +- 一次性暂存「更改」里的全部文件:点击**暂存全部**。 +- 取消暂存:点击「已暂存的更改」中该文件右侧的 `−` 按钮。仓库还没有任何提交时,这个操作同样可用。 - - 在消息输入框中填写提交信息。你在面板里继续操作时,输入的内容不会丢失。 +**暂存全部**等价于 `git add -A`:修改、新增和删除都会被暂存。 - - 点击 Commit,提交会被创建,文件列表随即刷新。 +## 提交 - - 如果消息输入框为空,点击 Commit 不会有任何效果,需要先填写提交信息。 +- 在消息输入框中填写提交信息。你在面板里继续操作时,输入的内容不会丢失。 +- 点击**提交**,提交会被创建,文件列表随即刷新。 +- 如果消息输入框为空,点击**提交**不会有任何效果,需要先填写提交信息。 ## 刷新文件列表 -面板会自动更新文件列表。如果你想立刻看到当前状态——比如刚在终端里执行过 Git 命令——点击 Refresh。 +面板会自动更新文件列表,最多每秒一次。如果你想立刻看到当前状态——比如刚在终端里执行过 Git 命令——点击标题栏右侧的 `⟳` 按钮。 + +## 故障排查 + +**面板提示当前环境无法使用 Git。** 系统没有安装 Git,或者 Editor 启动时的 `PATH` 里找不到它。安装 Git 后重启 Editor。 + +**点击提交没有任何反应。** 消息输入框是空的,需要先填写提交信息。 + +**`git commit` 报错询问你的身份。** Git 还没有配置用户信息。执行 `git config --global user.name "你的名字"` 和 `git config --global user.email "you@example.com"`。 + +**新建的文件一直留在「更改」里。** 未跟踪的文件会标记为 `?`,直到被暂存。 + ## 后续计划 -后续版本将支持分支显示与切换、文件状态着色、未暂存文件的丢弃改动、Push / Pull 控制以及 diff 预览。 \ No newline at end of file +后续版本将支持分支显示与切换、文件状态着色、未暂存文件的丢弃改动、Push / Pull 控制、diff 预览,以及异步执行 `git status`。 diff --git a/package/runtime/wokrlie/git_integration/__init__.py b/package/runtime/wokrlie/git_integration/__init__.py index fa07b92..4e08529 100644 --- a/package/runtime/wokrlie/git_integration/__init__.py +++ b/package/runtime/wokrlie/git_integration/__init__.py @@ -1,5 +1,7 @@ -"""Public runtime surface for the example plugin.""" +"""Runtime surface for the Git Integration plugin. -from .component import Null +The plugin is editor-only: it ships no gameplay components and no player +runtime code, so this module intentionally exposes nothing. +""" -__all__ = ["Null"] +__all__ = [] diff --git a/package/runtime/wokrlie/git_integration/component.py b/package/runtime/wokrlie/git_integration/component.py deleted file mode 100644 index 385583f..0000000 --- a/package/runtime/wokrlie/git_integration/component.py +++ /dev/null @@ -1,15 +0,0 @@ -"""Example gameplay component shipped to the player build.""" - -from infernux.components import InxComponent, serialized_field -from infernux.lib import Vector3, quatf -from infernux import Debug - - -class Null(InxComponent): - msg = "This plugin does not include any runtime components." - - def start(self): - Debug.log(self.msg) - - def update(self, delta_time: float) -> None: - """Called when updated""" \ No newline at end of file diff --git a/package/runtime/wokrlie/git_integration/preload.py b/package/runtime/wokrlie/git_integration/preload.py index 19e202c..bc5fbb0 100644 --- a/package/runtime/wokrlie/git_integration/preload.py +++ b/package/runtime/wokrlie/git_integration/preload.py @@ -1,9 +1,16 @@ -"""Early lifecycle for services that must exist in Editor and Player.""" +"""Runtime lifecycle hook for the Git Integration plugin. + +The plugin only provides an Editor panel, so there is nothing to register in +the player runtime. The hook is kept so the package keeps a stable runtime +role, and it is the documented place to initialise runtime services later. +""" from infernux.lifecycle import InxPreload, PreloadContext -class ExamplePluginPreload(InxPreload): +class GitIntegrationRuntimePreload(InxPreload): + """Runtime preload for a plugin that ships no runtime services.""" + def preload(self, context: PreloadContext) -> None: # Import heavy runtime dependencies here once, before scene scripts run. # Reversible resources should be registered with context.add_cleanup(). diff --git a/tests/test_translation_contracts.py b/tests/test_translation_contracts.py new file mode 100644 index 0000000..5be57e4 --- /dev/null +++ b/tests/test_translation_contracts.py @@ -0,0 +1,102 @@ +"""Keep the editor translation catalog and the panel that consumes it in sync. + +The Editor resolves a panel title through ``t(title_key)`` and falls back to +the raw key when the key is not declared. These tests make that failure +impossible to merge: every key the panel asks for must exist in both locales. +""" + +from pathlib import Path +import ast +import json +import unittest + + +ROOT = Path(__file__).resolve().parents[1] +PACKAGE = ROOT / "package" +EDITOR = PACKAGE / "editor" +PANEL = EDITOR / "wokrlie" / "git_integration" / "panel.py" +CATALOG = EDITOR / "translations.json" + +LOCALES = ("en", "zh") + + +def _catalog() -> dict: + return json.loads(CATALOG.read_text(encoding="utf-8")) + + +def _requested_keys() -> set[str]: + """Every translation key the panel asks the Editor to resolve.""" + tree = ast.parse(PANEL.read_text(encoding="utf-8"), filename=str(PANEL)) + keys: set[str] = set() + for node in ast.walk(tree): + if isinstance(node, ast.Call): + func = node.func + name = getattr(func, "id", None) or getattr(func, "attr", None) + if name != "t" or not node.args: + continue + first = node.args[0] + if isinstance(first, ast.Constant) and isinstance(first.value, str): + keys.add(first.value) + return keys + + +def _declared_title_key() -> str: + """The ``title_key`` passed to the ``@editor_panel`` decorator.""" + tree = ast.parse(PANEL.read_text(encoding="utf-8"), filename=str(PANEL)) + for node in ast.walk(tree): + if not isinstance(node, ast.Call): + continue + func = node.func + name = getattr(func, "id", None) or getattr(func, "attr", None) + if name != "editor_panel": + continue + for keyword in node.keywords: + if keyword.arg == "title_key" and isinstance(keyword.value, ast.Constant): + return str(keyword.value.value) + raise AssertionError("panel.py does not declare a title_key") + + +class TranslationCatalogTests(unittest.TestCase): + def test_catalog_declares_exactly_the_schema_and_locales(self): + document = _catalog() + self.assertEqual(set(document), {"$schema", "locales"}) + self.assertEqual(document["$schema"], "infernux.editor_translations") + + def test_catalog_locales_match_the_editor_locales(self): + self.assertEqual(set(_catalog()["locales"]), set(LOCALES)) + + def test_catalog_locales_declare_identical_key_sets(self): + locales = _catalog()["locales"] + english = set(locales["en"]) + chinese = set(locales["zh"]) + self.assertEqual(english, chinese) + + def test_catalog_keys_are_namespaced_and_non_empty(self): + for locale, entries in _catalog()["locales"].items(): + for key, value in entries.items(): + with self.subTest(locale=locale, key=key): + self.assertIn(".", key) + self.assertTrue(value.strip()) + + def test_every_requested_key_is_declared_in_every_locale(self): + locales = _catalog()["locales"] + for key in sorted(_requested_keys()): + for locale in LOCALES: + with self.subTest(key=key, locale=locale): + self.assertIn(key, locales[locale]) + + def test_panel_title_key_is_declared(self): + locales = _catalog()["locales"] + title_key = _declared_title_key() + for locale in LOCALES: + with self.subTest(locale=locale): + self.assertIn(title_key, locales[locale]) + + def test_panel_does_not_request_keys_outside_its_namespace(self): + for key in sorted(_requested_keys()): + with self.subTest(key=key): + self.assertTrue(key.startswith("wokrlie.git_integration.")) + + +if __name__ == "__main__": + unittest.main()