🔧 chore(playbook): add vendoring guide and sync scripts
This commit is contained in:
StarfishC
parent
151aaa13d0
commit
ef26056725
69
README.md
69
README.md
|
|
@ -37,6 +37,75 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
|
|||
- `.agents/code_quality.md`：代码质量底线与 review 清单。
|
||||
- `.agents/testing.md`：测试策略与何时补测试。
|
||||
|
||||
## 在其他项目中使用本 Playbook
|
||||
|
||||
由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范 vendoring 到项目内。
|
||||
|
||||
### 方式一：git subtree 同步（推荐）
|
||||
|
||||
1. 在目标项目中首次引入：
|
||||
|
||||
```bash
|
||||
git subtree add \
|
||||
--prefix docs/standards/tsl_playbook \
|
||||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||||
main --squash
|
||||
```
|
||||
|
||||
2. 后续同步更新：
|
||||
|
||||
```bash
|
||||
git subtree pull \
|
||||
--prefix docs/standards/tsl_playbook \
|
||||
https://git.mytsl.cn/csh/tsl-playbook.git \
|
||||
main --squash
|
||||
```
|
||||
|
||||
3. 目录约定（建议）
|
||||
|
||||
目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：
|
||||
|
||||
```txt
|
||||
.agents/ # 从 Playbook 同步后可按项目微调
|
||||
.gitattributes # 从 Playbook 同步
|
||||
docs/
|
||||
standards/
|
||||
tsl_playbook/ # git subtree 快照（只读）
|
||||
docs/ # code_style.md / naming.md / commit_message.md
|
||||
.agents/ # 标准代理规则快照
|
||||
.gitattributes
|
||||
SOURCE.md # 记录来源版本/commit（项目自行维护）
|
||||
project/ # 目标项目自己的文档
|
||||
README.md # 说明遵循 standards
|
||||
```
|
||||
|
||||
根目录的 `.agents/` 与 `.gitattributes` 通过同步脚本获得：
|
||||
|
||||
- 直接运行 Playbook 提供的脚本（子树快照里自带）：
|
||||
- `docs/standards/tsl_playbook/scripts/sync_playbook.sh`
|
||||
- `docs/standards/tsl_playbook/scripts/sync_playbook.ps1`
|
||||
- `docs/standards/tsl_playbook/scripts/sync_playbook.bat`
|
||||
- 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）。
|
||||
|
||||
这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。
|
||||
|
||||
### 方式二：手动复制快照
|
||||
|
||||
如果不使用 `git subtree`，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。
|
||||
|
||||
步骤：
|
||||
|
||||
1. 在目标项目创建目录：`docs/standards/tsl_playbook/`。
|
||||
2. 从本仓库复制以下内容到目标项目：
|
||||
- `docs/` → `docs/standards/tsl_playbook/docs/`
|
||||
- `.agents/` → `docs/standards/tsl_playbook/.agents/`
|
||||
- `.gitattributes` → `docs/standards/tsl_playbook/.gitattributes`
|
||||
- `scripts/` → `docs/standards/tsl_playbook/scripts/`
|
||||
3. 在目标项目根目录运行同步脚本，把 `.agents/` 与 `.gitattributes` 落到根目录（见上文脚本路径）。
|
||||
4. 在 `docs/standards/tsl_playbook/SOURCE.md` 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。
|
||||
|
||||
该方式没有自动同步能力，后续更新需重复上述复制流程。
|
||||
|
||||
## 版本与贡献
|
||||
|
||||
- 本项目会持续迭代；变更以 PR 形式提交。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,51 @@
|
|||
@echo off
|
||||
setlocal enabledelayedexpansion
|
||||
|
||||
rem Sync TSL Playbook snapshot to project root.
|
||||
rem - Copies docs\standards\tsl_playbook\.agents -> .agents
|
||||
rem - Copies docs\standards\tsl_playbook\.gitattributes -> .gitattributes
|
||||
rem Existing targets are backed up before overwrite.
|
||||
|
||||
for /f "delims=" %%R in ('git rev-parse --show-toplevel 2^>nul') do set "ROOT=%%R"
|
||||
if "%ROOT%"=="" set "ROOT=%cd%"
|
||||
|
||||
set "SRC=%ROOT%\docs\standards\tsl_playbook"
|
||||
set "AGENTS_SRC=%SRC%\.agents"
|
||||
set "GITATTR_SRC=%SRC%\.gitattributes"
|
||||
set "AGENTS_DST=%ROOT%\.agents"
|
||||
set "GITATTR_DST=%ROOT%\.gitattributes"
|
||||
|
||||
if not exist "%AGENTS_SRC%" (
|
||||
echo ERROR: Playbook snapshot not found at "%AGENTS_SRC%".
|
||||
echo Run: git subtree add --prefix docs/standards/tsl_playbook ^<playbook-url^> main --squash
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if exist "%AGENTS_DST%" (
|
||||
set "RAND=%RANDOM%"
|
||||
set "BAK_NAME=.agents.bak.!RAND!"
|
||||
ren "%AGENTS_DST%" "!BAK_NAME!"
|
||||
echo Backed up existing .agents -> !BAK_NAME!
|
||||
)
|
||||
|
||||
xcopy "%AGENTS_SRC%" "%AGENTS_DST%\" /e /i /y >nul
|
||||
if errorlevel 1 (
|
||||
echo ERROR: failed to copy .agents
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
echo Synced .agents from Playbook.
|
||||
|
||||
if exist "%GITATTR_SRC%" (
|
||||
if exist "%GITATTR_DST%" (
|
||||
set "RAND=%RANDOM%"
|
||||
set "BAK_NAME=.gitattributes.bak.!RAND!"
|
||||
ren "%GITATTR_DST%" "!BAK_NAME!"
|
||||
echo Backed up existing .gitattributes -> !BAK_NAME!
|
||||
)
|
||||
copy /y "%GITATTR_SRC%" "%GITATTR_DST%" >nul
|
||||
echo Synced .gitattributes from Playbook.
|
||||
)
|
||||
|
||||
echo Done.
|
||||
endlocal
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
# Sync TSL Playbook snapshot to project root.
|
||||
# - Copies docs/standards/tsl_playbook/.agents -> .agents
|
||||
# - Copies docs/standards/tsl_playbook/.gitattributes -> .gitattributes
|
||||
# Existing targets are backed up before overwrite.
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
$Root = (git rev-parse --show-toplevel 2>$null)
|
||||
if (-not $Root) { $Root = (Get-Location).Path }
|
||||
|
||||
$Src = Join-Path $Root "docs/standards/tsl_playbook"
|
||||
$AgentsSrc = Join-Path $Src ".agents"
|
||||
$GitAttrSrc = Join-Path $Src ".gitattributes"
|
||||
|
||||
if (-not (Test-Path $AgentsSrc)) {
|
||||
throw "Playbook snapshot not found at $AgentsSrc. Run git subtree add first."
|
||||
}
|
||||
|
||||
$timestamp = Get-Date -Format "yyyyMMddHHmmss"
|
||||
|
||||
$AgentsDst = Join-Path $Root ".agents"
|
||||
if (Test-Path $AgentsDst) {
|
||||
$bak = "$AgentsDst.bak.$timestamp"
|
||||
Move-Item $AgentsDst $bak
|
||||
Write-Host "Backed up existing .agents -> $bak"
|
||||
}
|
||||
Copy-Item $AgentsSrc $AgentsDst -Recurse -Force
|
||||
Write-Host "Synced .agents from Playbook."
|
||||
|
||||
$GitAttrDst = Join-Path $Root ".gitattributes"
|
||||
if (Test-Path $GitAttrSrc) {
|
||||
if (Test-Path $GitAttrDst) {
|
||||
$bak = "$GitAttrDst.bak.$timestamp"
|
||||
Move-Item $GitAttrDst $bak
|
||||
Write-Host "Backed up existing .gitattributes -> $bak"
|
||||
}
|
||||
Copy-Item $GitAttrSrc $GitAttrDst -Force
|
||||
Write-Host "Synced .gitattributes from Playbook."
|
||||
}
|
||||
|
||||
Write-Host "Done."
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
#!/usr/bin/env sh
|
||||
set -eu
|
||||
|
||||
# Sync TSL Playbook snapshot to project root.
|
||||
# - Copies docs/standards/tsl_playbook/.agents -> .agents
|
||||
# - Copies docs/standards/tsl_playbook/.gitattributes -> .gitattributes
|
||||
# Existing targets are backed up before overwrite.
|
||||
|
||||
ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
|
||||
SRC="$ROOT/docs/standards/tsl_playbook"
|
||||
AGENTS_SRC="$SRC/.agents"
|
||||
GITATTR_SRC="$SRC/.gitattributes"
|
||||
|
||||
if [ ! -d "$AGENTS_SRC" ]; then
|
||||
echo "ERROR: Playbook snapshot not found at $AGENTS_SRC" >&2
|
||||
echo "Run: git subtree add --prefix docs/standards/tsl_playbook <playbook-url> main --squash" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
timestamp="$(date +%Y%m%d%H%M%S 2>/dev/null || echo bak)"
|
||||
|
||||
AGENTS_DST="$ROOT/.agents"
|
||||
if [ -e "$AGENTS_DST" ]; then
|
||||
mv "$AGENTS_DST" "$ROOT/.agents.bak.$timestamp"
|
||||
echo "Backed up existing .agents -> .agents.bak.$timestamp"
|
||||
fi
|
||||
cp -R "$AGENTS_SRC" "$AGENTS_DST"
|
||||
|
||||
echo "Synced .agents from Playbook."
|
||||
|
||||
if [ -f "$GITATTR_SRC" ]; then
|
||||
GITATTR_DST="$ROOT/.gitattributes"
|
||||
if [ -e "$GITATTR_DST" ]; then
|
||||
mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp"
|
||||
echo "Backed up existing .gitattributes -> .gitattributes.bak.$timestamp"
|
||||
fi
|
||||
cp "$GITATTR_SRC" "$GITATTR_DST"
|
||||
echo "Synced .gitattributes from Playbook."
|
||||
fi
|
||||
|
||||
echo "Done."
|
||||
Loading…
Reference in New Issue