Skip to content

Commit a95f2d1

Browse files
FrostyHecFrostyHec
committed
feat(docs): add comprehensive language guidelines and local testing documentation
- Created language guidelines in Chinese to ensure consistency and accessibility for international contributors. - Added local testing guide detailing various testing methods and scripts. - Documented project structure explaining directory layout and dependency management. - Included publishing guide for releasing packages to PyPI and TestPyPI. - Implemented a language checker script to enforce English-only source code and documentation requirements.
1 parent 162d507 commit a95f2d1

36 files changed

Lines changed: 5414 additions & 1986 deletions

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
name: Bug Report
3+
about: Create a report to help us improve
4+
title: '[BUG] '
5+
labels: 'bug'
6+
assignees: ''
7+
---
8+
9+
## Bug Description
10+
11+
A clear and concise description of what the bug is.
12+
13+
## Steps to Reproduce
14+
15+
1. Go to '...'
16+
2. Click on '...'
17+
3. Run command '...'
18+
4. See error
19+
20+
## Expected Behavior
21+
22+
A clear and concise description of what you expected to happen.
23+
24+
## Actual Behavior
25+
26+
A clear and concise description of what actually happened.
27+
28+
## Error Message / Traceback
29+
30+
```
31+
Paste any error messages or tracebacks here
32+
```
33+
34+
## Environment
35+
36+
- **OS**: [e.g., Ubuntu 22.04, macOS 14.0, Windows 11]
37+
- **Python Version**: [e.g., 3.8.18]
38+
- **Package Version**: [e.g., 1.0.0]
39+
- **Installation Method**: [e.g., pip, conda]
40+
41+
## Minimal Reproducible Example
42+
43+
```python
44+
# Paste a minimal code example that reproduces the issue
45+
```
46+
47+
## Additional Context
48+
49+
Add any other context about the problem here.
50+
51+
## Checklist
52+
53+
- [ ] I have searched existing issues to ensure this is not a duplicate
54+
- [ ] I have provided all the requested information
55+
- [ ] I can reproduce this bug consistently

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Questions
4+
url: https://github.com/your-org/deep-solutions/discussions
5+
about: Ask questions and discuss with the community

‎.github/ISSUE_TEMPLATE/documentation.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: Documentation Improvement
3+
about: Suggest improvements or report issues with documentation
4+
title: '[DOCS] '
5+
labels: 'documentation'
6+
assignees: ''
7+
---
8+
9+
## Documentation Location
10+
11+
**Which documentation needs improvement?**
12+
13+
- [ ] README.md
14+
- [ ] Developer Guide (docs/developers_guide.md)
15+
- [ ] Project Structure (docs/project_structure.md)
16+
- [ ] Code Standards (docs/code_standards.md)
17+
- [ ] Local Testing (docs/local_testing.md)
18+
- [ ] CI Workflow (docs/ci_workflow.md)
19+
- [ ] Publishing Guide (docs/publishing.md)
20+
- [ ] API Documentation
21+
- [ ] Other: _____
22+
23+
## Issue Type
24+
25+
- [ ] Missing information
26+
- [ ] Incorrect/outdated information
27+
- [ ] Unclear explanation
28+
- [ ] Typo/grammar
29+
- [ ] Broken links
30+
- [ ] Missing examples
31+
- [ ] Translation issue (zh-CN)
32+
33+
## Current Content
34+
35+
**What does the documentation currently say? (if applicable)**
36+
37+
Quote or describe the current content.
38+
39+
## Suggested Improvement
40+
41+
**What should it say instead?**
42+
43+
Provide the suggested correction or addition.
44+
45+
## Additional Context
46+
47+
Add any other context about the documentation improvement here.
48+
49+
## Checklist
50+
51+
- [ ] I have searched existing issues to ensure this is not a duplicate
52+
- [ ] I have provided the specific location of the documentation issue

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
name: Feature Request
3+
about: Suggest an idea for this project
4+
title: '[FEATURE] '
5+
labels: 'enhancement'
6+
assignees: ''
7+
---
8+
9+
## Feature Summary
10+
11+
A clear and concise description of the feature you'd like to request.
12+
13+
## Problem / Motivation
14+
15+
**Is your feature request related to a problem? Please describe.**
16+
17+
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
18+
19+
## Proposed Solution
20+
21+
**Describe the solution you'd like**
22+
23+
A clear and concise description of what you want to happen.
24+
25+
## Alternative Solutions
26+
27+
**Describe alternatives you've considered**
28+
29+
A clear and concise description of any alternative solutions or features you've considered.
30+
31+
## Use Cases
32+
33+
Describe specific use cases where this feature would be beneficial:
34+
35+
1. Use case 1
36+
2. Use case 2
37+
3. Use case 3
38+
39+
## Example API / Usage
40+
41+
```python
42+
# If applicable, provide an example of how the feature might be used
43+
```
44+
45+
## Additional Context
46+
47+
Add any other context, screenshots, or mockups about the feature request here.
48+
49+
## Checklist
50+
51+
- [ ] I have searched existing issues/discussions to ensure this is not a duplicate
52+
- [ ] I have provided clear use cases for this feature
53+
- [ ] I am willing to help implement this feature (optional)

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
## Description
2+
<!-- Provide a brief description of the changes in this PR -->
3+
4+
5+
## Type of Change
6+
<!-- Mark with [x] the type that applies -->
7+
8+
- [ ] `feat`: New feature
9+
- [ ] `fix`: Bug fix
10+
- [ ] `docs`: Documentation only
11+
- [ ] `style`: Code style (formatting, no functional change)
12+
- [ ] `refactor`: Code refactoring (no new feature, no bug fix)
13+
- [ ] `perf`: Performance improvement
14+
- [ ] `test`: Adding or updating tests
15+
- [ ] `build`: Build system or dependencies
16+
- [ ] `ci`: CI/CD configuration
17+
- [ ] `chore`: Other changes (maintenance, tooling)
18+
19+
## Related Issues
20+
<!-- Link related issues: Closes #123, Fixes #456 -->
21+
22+
23+
## Checklist
24+
<!-- Mark completed items with [x] -->
25+
26+
- [ ] Code follows the project's style guidelines
27+
- [ ] Self-review of the code has been performed
28+
- [ ] Code comments have been added where necessary (English only)
29+
- [ ] Documentation has been updated (if applicable)
30+
- [ ] Tests have been added/updated
31+
- [ ] All tests pass locally (`./scripts/check.sh`)
32+
- [ ] No breaking changes (or documented in description)
33+
34+
## Screenshots (if applicable)
35+
<!-- Add screenshots for UI changes -->
36+
37+
38+
## Additional Notes
39+
<!-- Any additional information for reviewers -->
40+

‎.github/workflows/ci.yml‎

Lines changed: 44 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
# =============================================================================
2-
# CI Workflow - PR 检查
3-
# 触发条件: Pull Request 和 push 到 main 分支
4-
# 测试策略:
5-
# - PR/push: 仅测试 Python 3.8 (最小版本，快速反馈)
6-
# - main 分支: 全矩阵测试 Python 3.8-3.12 (完整回归测试)
7-
# 功能:
8-
# 1. 代码格式检查 (ruff)
9-
# 2. 类型检查 (mypy)
10-
# 3. 运行测试 (pytest + tox)
11-
# 安全模型: 本工作流不需要写权限，可安全运行 fork PR 代码
2+
# CI Workflow - PR Check
3+
# Trigger: Pull Request and push to main branch
4+
# Testing strategy:
5+
# - PR/push: Test only Python 3.8 (minimum version, fast feedback)
6+
# - main branch: Full matrix test Python 3.8-3.12 (complete regression)
7+
# Features:
8+
# 1. Code format check (ruff)
9+
# 2. Type check (mypy)
10+
# 3. Language check (no Chinese in source code)
11+
# 4. Run tests (pytest + tox)
12+
# Security: This workflow doesn't need write permission, safe for fork PRs
1213
# =============================================================================
1314

1415
name: CI
@@ -19,17 +20,17 @@ on:
1920
push:
2021
branches: [main]
2122

22-
# 自动取消同一分支的旧任务
23+
# Auto-cancel old tasks on same branch
2324
concurrency:
2425
group: ${{ github.workflow }}-${{ github.ref }}
2526
cancel-in-progress: true
2627

2728
permissions:
28-
contents: read # 只需要读权限
29+
contents: read # Read permission only
2930

3031
jobs:
3132
# ===========================================================================
32-
# 代码质量检查
33+
# Code Quality Check
3334
# ===========================================================================
3435
lint:
3536
name: Lint & Format Check
@@ -65,7 +66,26 @@ jobs:
6566
run: ruff check src/ tests/
6667

6768
# ===========================================================================
68-
# 类型检查
69+
# Language Check - No Chinese in source code
70+
# ===========================================================================
71+
language-check:
72+
name: Language Check
73+
runs-on: ubuntu-latest
74+
75+
steps:
76+
- name: Checkout code
77+
uses: actions/checkout@v4
78+
79+
- name: Set up Python
80+
uses: actions/setup-python@v5
81+
with:
82+
python-version: "3.8"
83+
84+
- name: Run language check
85+
run: python scripts/check_language.py
86+
87+
# ===========================================================================
88+
# Type Check
6989
# ===========================================================================
7090
type-check:
7191
name: Type Check
@@ -98,24 +118,24 @@ jobs:
98118
run: mypy src/
99119

100120
# ===========================================================================
101-
# 测试 - 差异化策略
102-
# PR: 仅测试 Python 3.8 (快速反馈)
103-
# main 分支: 全矩阵测试 Python 3.8-3.12 (完整回归)
121+
# Test - Differentiated Strategy
122+
# PR: Test only Python 3.8 (fast feedback)
123+
# main branch: Full matrix test Python 3.8-3.12 (complete regression)
104124
# ===========================================================================
105125
test:
106126
name: Test (Python ${{ matrix.python-version }})
107127
runs-on: ubuntu-latest
108128
strategy:
109129
fail-fast: false
110130
matrix:
111-
# PR 只测试最小版本，main 分支测试全矩阵
131+
# PR tests minimum version only, main branch tests full matrix
112132
python-version: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && fromJSON('["3.8", "3.9", "3.10", "3.11", "3.12"]') || fromJSON('["3.8"]') }}
113133

114134
steps:
115135
- name: Checkout code
116136
uses: actions/checkout@v4
117137
with:
118-
fetch-depth: 0 # setuptools-scm 需要 git 历史
138+
fetch-depth: 0 # setuptools-scm needs git history
119139

120140
- name: Set up Python ${{ matrix.python-version }}
121141
uses: actions/setup-python@v5
@@ -148,28 +168,28 @@ jobs:
148168
path: pytest-report.xml
149169
retention-days: 1
150170

151-
# 只在 Python 3.12 上上传覆盖率报告
171+
# Upload coverage report for all Python versions
152172
- name: Upload coverage report
153173
uses: actions/upload-artifact@v4
154-
if: always() && matrix.python-version == '3.12'
174+
if: always()
155175
with:
156176
name: coverage-${{ matrix.python-version }}-${{ github.run_id }}
157177
path: coverage.xml
158178
retention-days: 1
159179

160180
# ===========================================================================
161-
# 构建检查
181+
# Build Check
162182
# ===========================================================================
163183
build:
164184
name: Build Check
165185
runs-on: ubuntu-latest
166-
needs: [lint, type-check, test]
186+
needs: [lint, language-check, type-check, test]
167187

168188
steps:
169189
- name: Checkout code
170190
uses: actions/checkout@v4
171191
with:
172-
fetch-depth: 0 # setuptools-scm 需要完整的 git 历史
192+
fetch-depth: 0 # setuptools-scm needs full git history
173193

174194
- name: Set up Python
175195
uses: actions/setup-python@v5

‎.gitignore‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@ share/python-wheels/
3434
.installed.cfg
3535
*.egg
3636
MANIFEST
37-
src/deep_solutions/_version.py
3837

3938
# Virtual environments
4039
venv/
@@ -44,6 +43,12 @@ env.bak/
4443
venv.bak/
4544
.conda/
4645

46+
# Template
47+
src/deep_solutions/_version.py
48+
49+
# Linter
50+
.ruff_cache
51+
4752
# Testing
4853
.pytest_cache/
4954
.coverage

‎.gitmessage‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# <type>(<scope>): <subject>
2+
#
3+
# Types: feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert
4+
#
5+
# Examples:
6+
# feat(core): add data validation function
7+
# fix(utils): resolve parsing edge case
8+
# docs(readme): update installation guide
9+
#
10+
# Rules:
11+
# - Subject: imperative mood, no period, ≤50 chars
12+
# - Body: wrap at 72 chars, explain what and why
13+
# - Footer: reference issues (Closes #123)
14+
#
15+
# Breaking changes: add "BREAKING CHANGE:" in footer
16+
#
17+
# --- COMMIT MESSAGE STARTS BELOW THIS LINE ---
18+

0 commit comments

Comments
 (0)