outlookEmailPlus/CONTRIBUTING.md

Contributing to Outlook Email Management Tool / 为 Outlook 邮件管理工具做贡献

First off, thank you for considering contributing to this project! / 首先，感谢你考虑为此项目做贡献！

The following is a set of guidelines for contributing. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. / 以下是贡献指南。这些主要是指导方针，而非规则。请运用你的最佳判断，并随时在 PR 中提出对本文档的修改建议。

Table of Contents / 目录

• Code of Conduct
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Style Guidelines

Code of Conduct / 行为准则

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. / 此项目及其所有参与者均受我们的行为准则约束。参与即表示你同意遵守此准则。

How Can I Contribute? / 我如何做贡献？

Reporting Bugs / 报告 Bug

Before creating bug reports, please check the existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible: / 在创建 bug 报告之前，请检查现有 issue，你可能会发现无需创建新的。创建 bug 报告时，请尽可能包含详细信息：

• Use a clear and descriptive title / 使用清晰描述性的标题
• Describe the exact steps to reproduce the problem / 描述重现问题的确切步骤
• Provide specific examples / 提供具体示例
• Describe the behavior you observed and what you expected / 描述你观察到的行为以及你的期望
• Include screenshots if possible / 如可能，包含截图
• Include your environment details (OS, Python version, etc.) / 包含你的环境详情（操作系统、Python 版本等）

Suggesting Enhancements / 建议增强功能

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include: / 增强建议通过 GitHub issue 跟踪。创建增强建议时，请包含：

• Use a clear and descriptive title / 使用清晰描述性的标题
• Provide a detailed description of the suggested enhancement / 提供建议增强功能的详细描述
• Explain why this enhancement would be useful / 解释为什么此增强功能有用
• List some examples of how it would be used / 列出一些使用示例

Your First Code Contribution / 你的第一次代码贡献

Unsure where to begin? You can start by looking through beginner-friendly and help-wanted issues: / 不确定从哪里开始？你可以从 beginner-friendly 和 help-wanted issue 开始：

• Beginner-friendly issues - issues which should only require a few lines of code / 初学者友好的 issue - 只需几行代码即可解决
• Help wanted issues - issues which may be more involved / 需要帮助的 issue - 可能涉及更多内容

Development Setup / 开发环境设置

1. Fork the repository / Fork 仓库

2. Clone your fork / 克隆你的 fork

   git clone https://github.com/YOUR_USERNAME/outlookEmail.git
   cd outlookEmail
   

3. Create a virtual environment / 创建虚拟环境

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

4. Install dependencies / 安装依赖

   pip install -r requirements.txt
   

5. Create a branch for your changes / 为你的更改创建分支

   git checkout -b feature/your-feature-name
   

6. Make your changes and test them / 进行更改并测试

   python -m unittest discover -s tests -v
   

Pull Request Process / PR 流程

1. Ensure your code follows the project's coding standards / 确保你的代码遵循项目的编码标准
2. Update the documentation if needed / 如需要，更新文档
3. Add tests for new features / 为新功能添加测试
4. Ensure all tests pass / 确保所有测试通过
5. Update the README.md with details of changes if applicable / 如适用，更新 README.md 中的更改详情
6. Create a Pull Request with a clear title and description / 创建带有清晰标题和描述的 PR
7. Link any related issues in the PR description / 在 PR 描述中链接相关 issue

PR Title Format / PR 标题格式

Use conventional commit format: / 使用约定式提交格式：

• feat: Add new feature / feat: 添加新功能
• fix: Fix bug in email fetching / fix: 修复邮件获取中的 bug
• docs: Update README / docs: 更新 README
• style: Format code / style: 格式化代码
• refactor: Refactor authentication / refactor: 重构认证
• test: Add tests for email service / test: 为邮件服务添加测试
• chore: Update dependencies / chore: 更新依赖

Style Guidelines / 风格指南

Python Code Style / Python 代码风格

• Follow PEP 8 style guide / 遵循 PEP 8 风格指南
• Use meaningful variable and function names / 使用有意义的变量和函数名
• Add docstrings to functions and classes / 为函数和类添加文档字符串
• Keep functions small and focused / 保持函数小而专注
• Use type hints where appropriate / 在适当的地方使用类型提示

Git Commit Messages / Git 提交消息

• Use the present tense ("Add feature" not "Added feature") / 使用现在时（"Add feature" 而非 "Added feature"）
• Use the imperative mood ("Move cursor to..." not "Moves cursor to...") / 使用祈使语气（"Move cursor to..." 而非 "Moves cursor to..."）
• Limit the first line to 72 characters or less / 第一行限制在 72 个字符以内
• Reference issues and pull requests after the first line / 在第一行之后引用 issue 和 PR

Testing / 测试

• Write unit tests for new features / 为新功能编写单元测试
• Ensure all tests pass before submitting PR / 提交 PR 前确保所有测试通过
• Aim for high test coverage / 追求高测试覆盖率
• Test edge cases and error conditions / 测试边界情况和错误条件

Project Structure / 项目结构

outlook_web/
├── app.py                  # Application factory
├── routes/                 # Blueprint routes
├── controllers/            # Request handlers
├── services/               # Business logic
├── repositories/           # Data access
├── middleware/             # Middleware
└── security/               # Security modules

For detailed architecture information, see docs/DEV/00002-前后端拆分-开发者指南.md / 详细架构信息请参见 docs/DEV/00002-前后端拆分-开发者指南.md

Questions? / 有问题？

Feel free to open an issue with your question or reach out to the maintainers. / 随时开启 issue 提问或联系维护者。

License / 许可证

By contributing, you agree that your contributions will be licensed under the Apache License 2.0. / 通过贡献，你同意你的贡献将在 Apache License 2.0 下授权。

---

Thank you for contributing! / 感谢你的贡献！