项目初始化与规范

本文将介绍如何规范地初始化一个项目，包括项目结构、配置文件、版本控制等内容。

项目结构

一个规范的项目结构应该包含以下基本元素：

project/
├── .github/                    # GitHub 相关配置
│   └── workflows/             # GitHub Actions 工作流配置
├── docs/                      # 项目文档
│   ├── _static/              # 静态文件
│   ├── conf.py               # Sphinx 配置
│   └── index.md              # 文档首页
├── .gitignore                # Git 忽略文件
├── LICENSE                   # 开源许可证
└── README.md                 # 项目说明

版本控制最佳实践

分支管理

推荐使用以下分支策略：

  • main: 主分支，保持稳定

  • develop: 开发分支

  • feature/*: 特性分支

  • hotfix/*: 紧急修复分支

Git 提交规范

采用 Conventional Commits 规范：

<type>(<scope>): <description>

[optional body]

[optional footer]

常用的 type：

  • feat: 新功能

  • fix: 修复

  • docs: 文档更新

  • style: 代码格式

  • refactor: 重构

  • test: 测试

  • chore: 构建过程或辅助工具的变动

项目配置文件

.gitignore

创建适当的 .gitignore 文件以排除不必要的文件：

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
*.egg-info/
.installed.cfg
*.egg

# Sphinx documentation
docs/_build/

# IDE
.idea/
.vscode/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

LICENSE

选择合适的开源许可证，常见的选择包括：

  • MIT License：最宽松的许可证之一

  • Apache License 2.0：包含专利授权条款

  • GNU GPL：要求衍生作品必须开源

开发环境配置

Python 项目

  1. 使用 pyproject.toml 和 setup.cfg 管理项目元数据和依赖

  2. 使用 requirements.txt 或 Pipfile 管理依赖

  3. 配置 pre-commit 钩子进行代码质量检查

编辑器配置

创建 .editorconfig 文件统一代码风格：

root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true

[*.{json,yml,yaml,html,css,js}]
indent_size = 2

[Makefile]
indent_style = tab

下一步

  • 文档自动化：了解如何使用 Sphinx 和 ReadTheDocs 构建文档

  • CI/CD 实践：配置 GitHub Actions 实现自动化工作流