github-repository-architect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Repository Architect

GitHub 仓库架构师

Expert in creating production-ready GitHub repositories from scratch with comprehensive infrastructure, automation, and community standards. Provides end-to-end setup for open-source projects, enterprise codebases, and documentation sites with industry best practices.

专业从零开始创建符合生产环境要求的GitHub仓库，具备完善的基础设施、自动化流程和社区标准。遵循行业最佳实践，为开源项目、企业代码库和文档站点提供端到端的搭建服务。

Core Competencies

核心能力

1. Repository Foundation

1. 仓库基础设置

Initialization: Git configuration, .gitignore, license selection, README structure
Branch Strategy: Main/develop branches, protection rules, merge policies
Access Control: Team permissions, CODEOWNERS, branch protection
Repository Settings: Features enablement, security policies, merge options
Topics & Metadata: Discoverability optimization, GitHub search ranking

初始化：Git配置、.gitignore文件、许可证选择、README结构
分支策略：主分支/开发分支设置、保护规则、合并策略
访问控制：团队权限、CODEOWNERS、分支保护
仓库配置：功能启用、安全策略、合并选项
主题与元数据：可发现性优化、GitHub搜索排名提升

2. Community Health Files

2. 社区健康文件

README.md: Project overview, quick start, badges, contributing links
LICENSE: License selection and proper copyright attribution
CODE_OF_CONDUCT.md: Community standards and enforcement
CONTRIBUTING.md: Contribution guidelines and development workflow
SECURITY.md: Security policy and vulnerability reporting
CHANGELOG.md: Version history following Keep a Changelog format
CITATION.cff: Academic citation support (Citation File Format)

README.md：项目概述、快速开始、徽章、贡献链接
LICENSE：许可证选择与正确的版权归属
CODE_OF_CONDUCT.md：社区标准与执行规则
CONTRIBUTING.md：贡献指南与开发工作流
SECURITY.md：安全策略与漏洞上报流程
CHANGELOG.md：遵循Keep a Changelog格式的版本历史
CITATION.cff：学术引用支持（Citation File Format）

3. Issue & PR Templates

3. 议题与PR模板

Issue Templates: Bug reports, feature requests, documentation improvements
Pull Request Template: PR description structure, checklist, review guidelines
Discussion Templates: Q&A, ideas, announcements (if Discussions enabled)
Custom Forms: GitHub issue forms with type validation
Auto-labeling: Automatic label application based on issue type

议题模板：Bug报告、功能请求、文档改进
拉取请求模板：PR描述结构、检查清单、评审指南
讨论模板：问答、创意征集、公告（若启用Discussions功能）
自定义表单：带类型验证的GitHub议题表单
自动打标签：根据议题类型自动应用标签

4. CI/CD Automation

4. CI/CD自动化

GitHub Actions: Automated testing, linting, building, deployment
Quality Gates: Code coverage, security scanning, dependency audits
Release Automation: Semantic versioning, changelog generation, asset publishing
Documentation Deployment: GitHub Pages auto-deployment on push
Dependency Management: Dependabot, automated PR creation for updates

GitHub Actions：自动化测试、代码检查、构建、部署
质量门禁：代码覆盖率、安全扫描、依赖审计
发布自动化：语义化版本控制、变更日志生成、资产发布
文档部署：推送代码时自动部署GitHub Pages
依赖管理：Dependabot、自动创建更新PR

5. Documentation Site

5. 文档站点

GitHub Pages: Static site deployment (Jekyll, Docsify, MkDocs, or custom)
Site Structure: Hierarchical navigation, search functionality
Custom Domain: DNS configuration and HTTPS setup
SEO Optimization: Meta tags, sitemaps, structured data
Mobile Responsive: Cross-device compatibility testing

GitHub Pages：静态站点部署（支持Jekyll、Docsify、MkDocs或自定义方案）
站点结构：层级导航、搜索功能
自定义域名：DNS配置与HTTPS设置
SEO优化：元标签、站点地图、结构化数据
移动端适配：跨设备兼容性测试

Implementation Phases

实施阶段

Phase 1: Repository Initialization (30 min)

阶段1：仓库初始化（30分钟）

Step 1: Local Repository Setup

bash

undefined

步骤1：本地仓库设置

bash

undefined

Initialize git repository

git init git branch -M main

Create essential files

touch README.md LICENSE .gitignore

First commit

git add . git commit -m "chore: initialize repository"


**Step 2: GitHub Repository Creation**
```bash

git add . git commit -m "chore: initialize repository"


**步骤2：创建GitHub仓库**
```bash

Create on GitHub (via gh CLI)

gh repo create OWNER/REPO --public --source=. --remote=origin

Or use GitHub web interface for more options


**Step 3: Repository Settings**
- Enable Issues, Discussions, Projects (as needed)
- Disable Wiki (if using external docs)
- Set default branch to `main`
- Configure merge options (squash, rebase, merge commits)
- Enable "Automatically delete head branches"


**步骤3：仓库配置**
- 根据需要启用Issues、Discussions、Projects功能
- 若使用外部文档，禁用Wiki功能
- 将默认分支设置为`main`
- 配置合并选项（ squash、rebase、合并提交）
- 启用“自动删除头部分支”

Phase 2: Community Health Files (45 min)

阶段2：社区健康文件（45分钟）

README.md Template:

markdown

undefined

README.md模板：

markdown

undefined

Project Name

One-sentence project description

Features

Feature 1
Feature 2
Feature 3

Feature 1
Feature 2
Feature 3

Quick Start

```bash

Installation

npm install @org/package

Usage

import { function } from '@org/package' ```

Documentation

Full documentation: https://owner.github.io/repo

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE file for details.


**LICENSE Selection Guide:**
- **MIT**: Permissive, simple, widely used (recommended for most projects)
- **Apache 2.0**: Patent grant protection, enterprise-friendly
- **GPL v3**: Copyleft, derivatives must be open-source
- **CC BY-NC-ND 4.0**: Creative Commons for non-code content (documentation, frameworks)
- **Proprietary**: Custom license for closed-source with limited distribution

**CODE_OF_CONDUCT.md:**
Use Contributor Covenant (industry standard):
```bash

MIT License - see LICENSE file for details.


**许可证选择指南：**
- **MIT**：宽松许可、简单易用、应用广泛（大多数项目推荐）
- **Apache 2.0**：包含专利授权保护、适合企业场景
- **GPL v3**：Copyleft许可，衍生作品必须开源
- **CC BY-NC-ND 4.0**：针对非代码内容的Creative Commons许可（文档、框架）
- **专有许可**：针对闭源项目的自定义许可，限制分发

**CODE_OF_CONDUCT.md：**
使用行业标准的Contributor Covenant：
```bash

Via gh CLI

gh repo create-conduct

Or download from https://www.contributor-covenant.org/


**CONTRIBUTING.md Structure:**
1. Getting Started (development environment setup)
2. Development Workflow (branch naming, commit messages)
3. Pull Request Process (review criteria, testing requirements)
4. Code Style Guidelines (linting, formatting)
5. Testing Requirements (coverage thresholds, test types)
6. Documentation Standards (inline comments, external docs)

**SECURITY.md:**
```markdown


**CONTRIBUTING.md结构：**
1. 入门指南（开发环境搭建）
2. 开发工作流（分支命名、提交信息规范）
3. 拉取请求流程（评审标准、测试要求）
4. 代码风格指南（代码检查、格式化规则）
5. 测试要求（覆盖率阈值、测试类型）
6. 文档标准（内联注释、外部文档）

**SECURITY.md：**
```markdown

Security Policy

Supported Versions

Version	Supported
1.x	:white_check_mark:
< 1.0	:x:

Version	Supported
1.x	:white_check_mark:
< 1.0	:x:

Reporting a Vulnerability

DO NOT open a public issue for security vulnerabilities.

Email: security@example.com

Expected response time: 48 hours


**CHANGELOG.md:**
Follow [Keep a Changelog](https://keepachangelog.com/) format:
```markdown

DO NOT open a public issue for security vulnerabilities.

Email: security@example.com

Expected response time: 48 hours


**CHANGELOG.md：**
遵循[Keep a Changelog](https://keepachangelog.com/)格式：
```markdown

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[1.0.0] - 2025-11-01

Added

Initial release
Feature X
Feature Y

Initial release
Feature X
Feature Y

Changed

Updated dependency Z

Updated dependency Z

Fixed

Bug fix for issue #123


**CITATION.cff:**
```yaml
cff-version: 1.2.0
title: "Project Name"
message: "If you use this software, please cite it as below."
type: software
authors:
  - family-names: Last
    given-names: First
    email: author@example.com
    orcid: "https://orcid.org/0000-0000-0000-0000"
repository-code: "https://github.com/OWNER/REPO"
url: "https://owner.github.io/repo"
license: MIT
version: 1.0.0
date-released: 2025-11-01

Bug fix for issue #123


**CITATION.cff：**
```yaml
cff-version: 1.2.0
title: "Project Name"
message: "If you use this software, please cite it as below."
type: software
authors:
  - family-names: Last
    given-names: First
    email: author@example.com
    orcid: "https://orcid.org/0000-0000-0000-0000"
repository-code: "https://github.com/OWNER/REPO"
url: "https://owner.github.io/repo"
license: MIT
version: 1.0.0
date-released: 2025-11-01

Phase 3: Issue & PR Templates (30 min)

阶段3：议题与PR模板（30分钟）

Directory Structure:

.github/
├── ISSUE_TEMPLATE/
│   ├── bug_report.md
│   ├── feature_request.md
│   └── documentation.md
├── PULL_REQUEST_TEMPLATE.md
└── CODEOWNERS

Bug Report Template (.github/ISSUE_TEMPLATE/bug_report.md):

markdown

---
name: Bug Report
about: Report a bug or unexpected behavior
title: "[BUG] "
labels: bug
assignees: ''
---

目录结构：

.github/
├── ISSUE_TEMPLATE/
│   ├── bug_report.md
│   ├── feature_request.md
│   └── documentation.md
├── PULL_REQUEST_TEMPLATE.md
└── CODEOWNERS

Bug报告模板（.github/ISSUE_TEMPLATE/bug_report.md）：

markdown

---
name: Bug Report
about: Report a bug or unexpected behavior
title: "[BUG] "
labels: bug
assignees: ''
---

Description

A clear description of the bug.

Steps to Reproduce

Step 1
Step 2
See error

Step 1
Step 2
See error

Expected Behavior

What should happen.

Actual Behavior

What actually happens.

Environment

OS: [e.g., macOS 14.0]
Version: [e.g., 1.0.0]
Node: [e.g., 20.10.0]

OS: [e.g., macOS 14.0]
Version: [e.g., 1.0.0]
Node: [e.g., 20.10.0]

Additional Context

Screenshots, logs, or other context.


**Feature Request Template:**
```markdown
---
name: Feature Request
about: Suggest a new feature or enhancement
title: "[FEATURE] "
labels: enhancement
assignees: ''
---

Screenshots, logs, or other context.


**功能请求模板：**
```markdown
---
name: Feature Request
about: Suggest a new feature or enhancement
title: "[FEATURE] "
labels: enhancement
assignees: ''
---

Problem Statement

What problem does this solve?

Proposed Solution

How should it work?

Alternatives Considered

Other approaches you've thought about.

Additional Context

Any other relevant information.


**Pull Request Template (.github/PULL_REQUEST_TEMPLATE.md):**
```markdown

Any other relevant information.


**拉取请求模板（.github/PULL_REQUEST_TEMPLATE.md）：**
```markdown

Description

Brief description of changes.

Type of Change

Bug fix (non-breaking change fixing an issue)
New feature (non-breaking change adding functionality)
Breaking change (fix or feature causing existing functionality to break)
Documentation update

Bug fix (non-breaking change fixing an issue)
New feature (non-breaking change adding functionality)
Breaking change (fix or feature causing existing functionality to break)
Documentation update

Testing

Checklist

Related Issues

Closes #(issue number)


**CODEOWNERS (.github/CODEOWNERS):**

Closes #(issue number)


**CODEOWNERS（.github/CODEOWNERS）：**

Global owners

@organization/maintainers

@organization/maintainers

Specific paths

/docs/ @organization/docs-team /src/ @organization/core-team /.github/ @organization/devops-team /tests/ @organization/qa-team

undefined

/docs/ @organization/docs-team /src/ @organization/core-team /.github/ @organization/devops-team /tests/ @organization/qa-team

undefined

Phase 4: CI/CD Workflows (60 min)

阶段4：CI/CD工作流（60分钟）

Lint Workflow (.github/workflows/lint.yml):

yaml

name: Lint

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run ESLint
        run: npm run lint
      
      - name: Run Prettier
        run: npm run format:check

Test Workflow (.github/workflows/test.yml):

yaml

name: Test

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18.x, 20.x]
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/lcov.info

Release Workflow (.github/workflows/release.yml):

yaml

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          draft: false
          prerelease: false

GitHub Pages Deploy (.github/workflows/pages.yml):

yaml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Pages
        uses: actions/configure-pages@v4
      
      - name: Build site
        run: |
          # Build commands here
          npm run build:docs
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

代码检查工作流（.github/workflows/lint.yml）：

yaml

name: Lint

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run ESLint
        run: npm run lint
      
      - name: Run Prettier
        run: npm run format:check

测试工作流（.github/workflows/test.yml）：

yaml

name: Test

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18.x, 20.x]
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/lcov.info

发布工作流（.github/workflows/release.yml）：

yaml

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          draft: false
          prerelease: false

GitHub Pages部署工作流（.github/workflows/pages.yml）：

yaml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Pages
        uses: actions/configure-pages@v4
      
      - name: Build site
        run: |
          # Build commands here
          npm run build:docs
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Phase 5: Documentation Site (60 min)

阶段5：文档站点（60分钟）

Option 1: Docsify (Recommended for simplicity)

Create
```
docs/
```
directory structure:

docs/
├── index.html (Docsify config)
├── README.md (Home page)
├── _sidebar.md (Navigation)
├── guide/
│   ├── getting-started.md
│   └── advanced.md
└── reference/
    ├── api.md
    └── cli.md

```
docs/index.html
```
:

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Project Documentation</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'Project Name',
      repo: 'https://github.com/owner/repo',
      loadSidebar: true,
      subMaxLevel: 2,
      search: 'auto'
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>
</html>

```
docs/_sidebar.md
```
:

markdown

- [Home](/)
- [Getting Started](guide/getting-started.md)
- [API Reference](reference/api.md)

Option 2: Jekyll (GitHub Pages default)

Create
```
_config.yml
```
:

yaml

title: Project Documentation
description: Project description
theme: jekyll-theme-cayman
markdown: kramdown

Enable GitHub Pages in repository settings
Select source:
```
main
```
branch,
```
/docs
```
folder

Option 3: MkDocs (Python-based, feature-rich)

Install:
```
pip install mkdocs mkdocs-material
```
Initialize:
```
mkdocs new .
```
Configure
```
mkdocs.yml
```
Build:
```
mkdocs build
```
Deploy:
```
mkdocs gh-deploy
```

选项1：Docsify（推荐，操作简单）

创建
```
docs/
```
目录结构：

docs/
├── index.html (Docsify config)
├── README.md (Home page)
├── _sidebar.md (Navigation)
├── guide/
│   ├── getting-started.md
│   └── advanced.md
└── reference/
    ├── api.md
    └── cli.md

```
docs/index.html
```
：

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Project Documentation</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'Project Name',
      repo: 'https://github.com/owner/repo',
      loadSidebar: true,
      subMaxLevel: 2,
      search: 'auto'
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>
</html>

```
docs/_sidebar.md
```
：

markdown

- [Home](/)
- [Getting Started](guide/getting-started.md)
- [API Reference](reference/api.md)

选项2：Jekyll（GitHub Pages默认方案）

创建
```
_config.yml
```
：

yaml

title: Project Documentation
description: Project description
theme: jekyll-theme-cayman
markdown: kramdown

在仓库配置中启用GitHub Pages
选择源码：
```
main
```
分支，
```
/docs
```
文件夹

选项3：MkDocs（基于Python，功能丰富）

安装：
```
pip install mkdocs mkdocs-material
```
初始化：
```
mkdocs new .
```
配置
```
mkdocs.yml
```
构建：
```
mkdocs build
```
部署：
```
mkdocs gh-deploy
```

Phase 6: Badges & Metadata (15 min)

阶段6：徽章与元数据（15分钟）

Essential Badges:

markdown

[![Version](https://img.shields.io/github/v/release/OWNER/REPO)](https://github.com/OWNER/REPO/releases)
[![License](https://img.shields.io/github/license/OWNER/REPO)](LICENSE)
[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions)
[![Coverage](https://codecov.io/gh/OWNER/REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/OWNER/REPO)
[![npm](https://img.shields.io/npm/v/@org/package)](https://www.npmjs.com/package/@org/package)

Repository Topics:

Maximum 20 topics
Use lowercase, hyphens for spaces
Include: language, framework, use-case, industry

Example:

typescript

api

mental-models

cognitive-framework

About Section:

Concise description (160 chars max)
Include primary use case
Add website URL if applicable
Select appropriate topics

必备徽章：

markdown

[![Version](https://img.shields.io/github/v/release/OWNER/REPO)](https://github.com/OWNER/REPO/releases)
[![License](https://img.shields.io/github/license/OWNER/REPO)](LICENSE)
[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions)
[![Coverage](https://codecov.io/gh/OWNER/REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/OWNER/REPO)
[![npm](https://img.shields.io/npm/v/@org/package)](https://www.npmjs.com/package/@org/package)

仓库主题：

最多20个主题
使用小写，用连字符代替空格
包含：编程语言、框架、使用场景、行业领域

示例：

typescript

api

mental-models

cognitive-framework

关于部分：

简洁描述（最多160字符）
包含主要使用场景
若有官网，添加官网URL
选择合适的主题

Quality Checklist

质量检查清单

Repository Health ✅

仓库健康 ✅

Automation ✅

自动化 ✅

Templates ✅

模板 ✅

Bug report template
Feature request template
Pull request template with checklist
CODEOWNERS file for automatic review assignment

Bug报告模板
功能请求模板
带检查清单的拉取请求模板
CODEOWNERS文件用于自动分配评审

Documentation ✅

文档 ✅

Metadata ✅

元数据 ✅

Repository description set
Topics configured (10-20 relevant tags)
Website URL added (if applicable)
Social preview image (1280x640px)

已设置仓库描述
已配置主题（10-20个相关标签）
已添加官网URL（若有）
已设置社交预览图（1280x640px）

Best Practices

最佳实践

Branch Protection Rules

分支保护规则

Settings → Branches → Add rule

Branch name pattern: main

Protection settings:
✅ Require pull request before merging
  ✅ Require approvals (1-2)
  ✅ Dismiss stale reviews
✅ Require status checks to pass
  ✅ Require branches to be up to date
✅ Require conversation resolution before merging
✅ Require signed commits (optional, high security)
✅ Include administrators (recommended)

Settings → Branches → Add rule

Branch name pattern: main

Protection settings:
✅ Require pull request before merging
  ✅ Require approvals (1-2)
  ✅ Dismiss stale reviews
✅ Require status checks to pass
  ✅ Require branches to be up to date
✅ Require conversation resolution before merging
✅ Require signed commits (optional, high security)
✅ Include administrators (recommended)

Semantic Versioning

语义化版本控制

MAJOR.MINOR.PATCH (e.g., 2.1.3)

MAJOR: Breaking changes
MINOR: New features (backwards compatible)
PATCH: Bug fixes (backwards compatible)

Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1
Build metadata: 1.0.0+20130313144700

MAJOR.MINOR.PATCH (e.g., 2.1.3)

MAJOR: Breaking changes
MINOR: New features (backwards compatible)
PATCH: Bug fixes (backwards compatible)

Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1
Build metadata: 1.0.0+20130313144700

Commit Message Convention

提交信息规范

<type>(<scope>): <subject>

<body>

<footer>

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- style: Formatting, no code change
- refactor: Code change (neither fix nor feature)
- perf: Performance improvement
- test: Adding or updating tests
- chore: Maintenance (dependencies, config)
- ci: CI/CD changes

Examples:
feat(api): add mental model search endpoint
fix(parser): handle empty input gracefully
docs(readme): update installation instructions

<type>(<scope>): <subject>

<body>

<footer>

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- style: Formatting, no code change
- refactor: Code change (neither fix nor feature)
- perf: Performance improvement
- test: Adding or updating tests
- chore: Maintenance (dependencies, config)
- ci: CI/CD changes

Examples:
feat(api): add mental model search endpoint
fix(parser): handle empty input gracefully
docs(readme): update installation instructions

Release Process

发布流程

bash

undefined

bash

undefined

1. Update version

1. 更新版本

npm version [patch|minor|major]

2. Update CHANGELOG.md

2. 更新CHANGELOG.md

Add new version section with changes

添加新版本的变更内容

3. Commit changes

3. 提交变更

git add . git commit -m "chore: release v1.2.0"

4. Create and push tag

4. 创建并推送标签

git tag -a v1.2.0 -m "Release v1.2.0" git push origin main --tags

5. GitHub Actions automatically creates release

5. GitHub Actions自动创建发布

Or manually via gh CLI:

或通过gh CLI手动创建：

gh release create v1.2.0 --title "v1.2.0" --notes-file RELEASE_NOTES.md

undefined

gh release create v1.2.0 --title "v1.2.0" --notes-file RELEASE_NOTES.md

undefined

Common Pitfalls

常见陷阱

Pitfall 1: Incomplete .gitignore

陷阱1：.gitignore文件不完整

Problem: Sensitive files or build artifacts committed
Solution: Use gitignore.io templates, review before first commit

问题： 敏感文件或构建产物被提交
解决方案： 使用gitignore.io模板，首次提交前仔细检查

Pitfall 2: No Branch Protection

陷阱2：未设置分支保护

Problem: Direct pushes to main, untested code in production
Solution: Enable branch protection immediately after repo creation

问题： 直接推送到主分支，未经测试的代码进入生产环境
解决方案： 创建仓库后立即启用分支保护

Pitfall 3: Unclear Contributing Guidelines

陷阱3：贡献指南不清晰

Problem: Poor quality PRs, inconsistent code style
Solution: Detailed CONTRIBUTING.md with examples and linting automation

问题： PR质量低下，代码风格不一致
解决方案： 编写详细的CONTRIBUTING.md并搭配代码检查自动化

Pitfall 4: Missing CI/CD

陷阱4：缺少CI/CD

Problem: Broken code merged, manual deployment friction
Solution: Set up basic CI before accepting first PR

问题： 有问题的代码被合并，手动部署效率低下
解决方案： 接受第一个PR前先搭建基础CI流程

Pitfall 5: Stale Documentation

陷阱5：文档过时

Problem: Docs out of sync with code
Solution: Automate docs deployment, make docs updates part of PR checklist

问题： 文档与代码不一致
解决方案： 自动化文档部署，将文档更新纳入PR检查清单

Resources

资源

GitHub Docs: https://docs.github.com
Keep a Changelog: https://keepachangelog.com
Semantic Versioning: https://semver.org
Contributor Covenant: https://www.contributor-covenant.org
Citation File Format: https://citation-file-format.github.io
GitHub Actions Marketplace: https://github.com/marketplace?type=actions

GitHub Docs: https://docs.github.com
Keep a Changelog: https://keepachangelog.com
Semantic Versioning: https://semver.org
Contributor Covenant: https://www.contributor-covenant.org
Citation File Format: https://citation-file-format.github.io
GitHub Actions Marketplace: https://github.com/marketplace?type=actions

Success Criteria

成功标准

Production-ready repository includes:

✅ All community health files present and complete
✅ Automated testing and linting via GitHub Actions
✅ Branch protection preventing untested code in main
✅ Clear contribution guidelines and templates
✅ GitHub Pages documentation site live
✅ Proper versioning and release automation
✅ Security policy and vulnerability reporting process
✅ Repository discoverable via topics and description

Repository fails if:

❌ Missing LICENSE or unclear licensing
❌ No CI/CD, manual testing only
❌ Direct commits to main possible
❌ No documentation or stale docs
❌ No contribution guidelines
❌ Security vulnerabilities in dependencies

生产级仓库包含以下内容：

✅ 所有社区健康文件齐全且完整
✅ 通过GitHub Actions实现自动化测试和代码检查
✅ 分支保护机制防止未经测试的代码进入主分支
✅ 清晰的贡献指南和模板
✅ GitHub Pages文档站点已上线
✅ 规范的版本控制和发布自动化
✅ 安全策略和漏洞上报流程
✅ 通过主题和描述提升仓库可发现性

仓库不合格的情况：

❌ 缺少LICENSE文件或许可说明不清晰
❌ 无CI/CD，仅依赖手动测试
❌ 可直接提交到主分支
❌ 无文档或文档过时
❌ 无贡献指南
❌ 依赖中存在安全漏洞