贡献指南

感谢您对 Django Admin Dashboards 贡献指南感兴趣！本指南将帮助您搭建开发环境、理解代码库并提交贡献。

开发环境

1. 克隆仓库

    git clone https://gitee.com/rRR0VrFP/django-admin-dashboards.git
    cd django-admin-dashboards

2. 安装开发依赖

使用 dev 可选依赖组：

    pip install -e ".[dev]"

这将安装：

• pytest 和 pytest-django 用于测试 - black 用于代码格式化 - flake8 用于代码检查

3. 设置演示项目

仓库包含一个用于测试的 Django 演示项目：

    cd django_admin_dashboards_demo
    python manage.py migrate
    python manage.py collectstatic --noinput

4. 运行开发服务器

    python manage.py runserver

访问 http://localhost:8000/admin/ 查看数据看板运行效果（管理员凭据：admin/admin）。

代码风格

Python 代码

我们使用 Black 进行代码格式化，使用 Flake8 进行代码检查。

    # Format code with Black

    black django_admin_dashboards/

    # Check code style with Flake8

    flake8 django_admin_dashboards/

模板代码

HTML 模板遵循 Django 模板约定：

• 使用 2 空格缩进
• 复杂部分包含注释
• 保持模板逻辑简洁
• 适当使用模板标签和过滤器

CSS/JavaScript

• 使用描述性的类名，类似 BEM 命名法（dashboard__card--highlighted）
• 根据需要包含浏览器厂商前缀
• 注释复杂的 CSS 规则

测试

运行测试

    # Run all tests

    pytest

    # Run tests with verbose output

    pytest -v

    # Run specific test file

    pytest django_admin_dashboards_example

    # Run tests with coverage

    pytest --cov=django_admin_dashboards

测试结构

测试位于 django_admin_dashboards_example/tests.py 中，包括： - 数据看板渲染测试 - 组件功能测试 - URL 参数处理测试 - 深色模式和全屏测试 - 模板标签测试

编写测试

添加新功能时，请包含相应的测试：

1. 单元测试 针对单个函数/方法
2. 集成测试 针对组件交互
3. 模板测试 针对渲染输出
4. JavaScript 测试（如果适用）

示例测试结构：

    def test_new_feature():
        # Arrange

        dashboard = MyDashboard(request=request)

        # Act

        result = dashboard.get_layout()

        # Assert

        assert result is not None
        # Add specific assertions

拉取请求流程

1. 创建分支

    git checkout -b feature/your-feature-name

使用描述性的分支名称：

• 功能/ 用于新功能
• 修复/ 用于错误修复
• 文档/ 用于文档
• 重构/ 用于代码重构

2. 进行更改

• 编写清晰、专注的提交
• 为新功能包含测试
• 根据需要更新文档
• 遵循代码风格指南

3. 提交信息

使用约定式提交格式：

    type(scope): description

    [optional body]

    [optional footer]

类型：

• feat: 新功能 - fix: 错误修复 - docs: 文档变更 - style: 代码风格变更（格式化等） - refactor: 代码重构 - test: 添加或更新测试 - chore: 维护任务

示例：

    feat(dashboard): add export functionality to tables

    - Add CSV export button to TableComponent
    - Include export options in dashboard settings
    - Update documentation with export examples

4. 运行提交前检查

提交拉取请求前，请确保：

    # Run tests

    pytest

    # Check code style

    flake8 django_admin_dashboards/

    # Format code

    black django_admin_dashboards/

    # Build documentation (if changed)

    mkdocs build

5. 提交拉取请求

1. 将分支推送到 Gitee
2. 针对 main 分支创建拉取请求
3. 填写 PR 模板，包括：
4. 变更描述
5. 相关 issue
6. 执行的测试
7. 截图（如果是 UI 变更）

6. 代码审查

• 及时响应审查反馈
• 按要求进行更改
• 保持提交专注，必要时进行变基
• 确保 CI 测试通过

项目结构

Django Admin Dashboards 主包结构如下：

django_admin_dashboards/
├── __init__.py              # 包元数据和版本导出
├── admin.py                 # Django Admin 集成
├── apps.py                  # Django 应用配置
├── base.py                  # 基类：Dashboard、Component、Layout 等
├── models.py                # 数据库模型（如有）
├── views.py                 # 自定义视图（如有）
├── urls.py                  # URL 配置
├── contrib/                 # 贡献的组件和功能
│   └── auth/                # 认证应用相关
│       ├── __init__.py      # 包初始化
│       └── dashboard.py     # Auth 应用数据看板实现
├── templatetags/            # 模板标签
│   └── dashboard_tags.py    # 数据看板渲染标签
├── static/django_admin_dashboards/  # 静态资源
│   ├── css/                 # CSS 样式文件
│   │   ├── dashboard.css    # 全局数据看板样式
│   │   ├── card.css         # 卡片组件样式
│   │   ├── chart.css        # 图表组件样式
│   │   ├── table.css        # 表格组件样式
│   │   └── filter.css       # 过滤器组件样式
│   └── js/                  # JavaScript 文件
│       ├── dashboard.js     # 全局数据看板 JavaScript
│       ├── card.js          # 卡片组件 JavaScript
│       ├── chart.js         # 图表组件 JavaScript
│       ├── table.js         # 表格组件 JavaScript
│       └── filter.js        # 过滤器组件 JavaScript
├── templates/admin/         # 数据看板模板
│   ├── dashboard.html       # 主数据看板模板
│   ├── index.html           # Admin 首页覆盖模板
│   ├── app_index.html       # 应用页面覆盖模板
│   └── components/          # 组件模板
│       ├── card.html        # 卡片组件模板
│       ├── chart.html       # 图表组件模板
│       ├── table.html       # 表格组件模板
│       └── filter.html      # 过滤器组件模板
└── locale/                  # 翻译文件
    └── zh_Hans/             # 中文（简体）翻译
        └── LC_MESSAGES/
            ├── django.po    # 翻译源文件
            └── django.mo    # 编译后的翻译文件

关键文件

• base.py: 包含 Dashboard、Layout 和所有组件类
• templates/admin/index.html: 主数据看板模板
• static/django_admin_dashboards/css/dashboard.css: 所有数据看板样式
• templatetags/dashboard_tags.py: 用于渲染的模板标签

添加新组件

1. 创建组件类

在 base.py 中扩展 Component：

    class NewComponent(Component):
        component_type = "new"

        def __init__(self, title="", data=None, **kwargs):
            super().__init__(**kwargs)
            self.title = title
            self.data = data or {}

        def get_context_data(self, request):
            context = super().get_context_data(request)
            context.update({
                "title": self.title,
                "data": self.data,
            })
            return context

2. 创建模板

创建 模板/admin/components/new.HTML：

    {% load i18n %}
    <div class="new-component {{ css_class }}"{% if css_id %} id="{{ css_id }}"{% endif %}>
        <h3>{{ title }}</h3>
        <div class="new-content">

        </div>
    </div>

3. 添加 CSS 样式

更新 dashboard.css：

    .dashboard .new-component {
        /* Component styles */
    }

    .dashboard .new-component h3 {
        /* Title styles */
    }

    /* Dark mode support */
    html[data-theme="dark"] .dashboard .new-component {
        /* Dark mode styles */
    }

4. 更新文档

• 将组件添加到 docs/API/components.md
• 在 docs/示例/ 中创建使用示例
• 更新 docs/user-guide/components.md

翻译

添加新字符串

1. 使用 gettext 或 gettext_lazy 添加可翻译字符串：

    from django.utils.translation import gettext as _

    class MyDashboard(Dashboard):
        title = _("My Dashboard")

1. 提取消息：

    cd django_admin_dashboards
    django-admin makemessages -l zh_Hans

1. 编辑 locale/zh_Hans/LC_MESSAGES/Django.po 中的 .po 文件

2. 编译消息：

    django-admin compilemessages

支持新语言

1. 创建新的本地化目录：

    django-admin makemessages -l es

1. 翻译 .po 文件
2. 编译消息
3. 测试时更新演示项目中的 LANGUAGES

文档

构建文档

    # Install documentation dependencies

    pip install mkdocs mkdocs-material mkdocstrings-python

    # Serve documentation locally

    mkdocs serve

    # Build documentation

    mkdocs build

文档结构

• docs/索引.md: 首页
• docs/getting-started/: 安装和设置
• docs/user-guide/: 使用说明
• docs/API/: API 参考
• docs/示例/: 数据看板示例
• docs/开发/: 开发指南

添加文档

1. 在相应章节创建新的 markdown 文件
2. 添加到 mkdocs.yml 的导航中
3. 包含代码示例和截图
4. 使用警示框标注注释、警告和提示

问题报告

报告前

1. 检查现有 issue 避免重复
2. 搜索文档寻找解决方案
3. 使用最新版本测试

创建 issue

包含：

• 问题的清晰描述
• 重现步骤
• 预期与实际行为对比
• 截图（如果适用）
• 环境详情（Django 版本、Python 版本等）
• 错误消息和日志

发布流程

发布遵循语义化版本控制：

• MAJOR: 破坏性变更
• MINOR: 新功能（向后兼容）
• PATCH: 错误修复（向后兼容）

发布步骤

1. 更新 pyproject.toml 和 __init__.py 中的版本
2. 更新 docs/development/changelog.md（如果维护）
3. 运行完整测试套件
4. 本地构建并测试包
5. 创建 git 标签
6. 推送到 PyPI
7. 更新文档

获取帮助

• 阅读 文档
• 搜索 Gitee问题
• 在讨论区提问（如果启用）

行为准则

所有贡献者都应遵循项目的行为准则。请保持尊重、包容和协作。

---

感谢您为 Django Admin Dashboards 贡献指南！您的努力让这个项目变得更好。

---