后端电商【免费下载链接】django-oscarDomain-driven e-commerce for Django项目地址https://gitcode.com/gh_mirrors/dj/django-oscar点击查看免费下载django-oscar 是一个基于 Django 的领域驱动型电商框架其核心代码、12 个业务应用与测试体系分布在src/oscar/、tests/等目录中。本篇指南以仓库 贡献指南总览 为骨架系统梳理参与 Oscar 开发的完整工作流从 Fork 仓库、搭建本地沙箱环境到编写符合规范的代码、运行测试套件、维护文档并最终提交 Pull Request。读完本文你将掌握一套可直接上手执行的 Oscar 协作开发方案以及其背后由Makefile、tox.ini、setup.cfg等仓库文件支撑的自动化工具链。一、你能以哪些方式参与 Oscar任何形式的帮助都值得欢迎贡献不局限于写代码贡献指南 明确列出了六条参与路径加入 django-oscar 邮件列表回答其他开发者提出的问题在问题追踪器ticket tracker中报告 Bug针对新行为或修复行为提交 Pull Request改进项目文档编写测试用例通过 Transifex 平台参与翻译工作申请一个语言即可开始。二、搭建开发环境Fork、Clone 与 make install开发环境是参与贡献的第一步。开发环境搭建文档 给出了标准流程先 Fork 仓库再克隆到本地创建虚拟环境并安装依赖$ git clone gitgithub.com:username/django-oscar.git $ cd django-oscar $ mkvirtualenv oscar # 需要 virtualenvwrapper $ make install其中make install的目标在仓库根目录的 Makefile 中有明确定义它首先执行assets目标npm install与npm run build用于安装并构建前端静态资源然后执行pip install -e .[test] --upgrade --upgrade-strategyeager即以可编辑模式安装 Oscar 本体并附带test扩展依赖。这意味着一次make install即可同时就绪 Python 侧与前端侧的开发依赖。如果你的系统是 Ubuntu部分包在编译阶段需要python3-dev头文件请先确保该包已安装。2.1 创建本地沙箱站点Sandbox文档建议使用沙箱站点在本地检视改动效果一条命令即可完成$ make sandbox该命令在 Makefile 中被定义为install加上build_sandbox。build_sandbox会依次执行sandbox_clean清理媒体目录、缓存、静态文件与 SQLite 数据库并执行migrate、sandbox_load_user加载sandbox/fixtures/auth.json用户数据和sandbox_load_data按顺序导入商品 CSV、图片、国家、页面、范围、优惠、订单等 fixture并构建搜索索引、收集静态文件。这一串任务正是sandbox/目录下完整演示站点得以一键成型的原因。沙箱站点本身是一个「原味 Oscar」站点相关细节可参考沙箱文档。2.2 JPEG 图像支持UbuntuOscar 使用 Pillow 处理商品图片在 Ubuntu 上需要先安装系统级图像库$ sudo apt-get install python3-dev libjpeg-dev libfreetype6-dev zlib1g-dev如果你此前通过make install已经安装过 PillowPIL需要重装以启用 JPEG 支持$ pip uninstall Pillow $ pip install Pillow2.3 基于沙箱生成数据库迁移由于沙箱是一个标准的 Oscar 站点它正是团队用来生成迁移文件的基准环境。需要新增迁移时$ make sandbox $ sandbox/manage.py makemigrations2.4 使用 npm 开发 SCSS/CSSOscar 的 CSS 使用 SASS 构建。package.json中声明了buildgulp copy gulp scss与watchgulp watch两个脚本对应的 gulp 任务位于 gulpfile.js/index.js 及其subtasks/子目录中开发 SCSS 源码时运行npm run watch监听源文件变更并自动编译为输出 CSS需要手动编译全部静态资源时运行npm run build。SCSS 源文件位于 src/oscar/static_src/oscar/其中包含 21 个.scss文件与前端 JS。2.5 在 PostgreSQL 上测试迁移默认沙箱使用 SQLite而生产环境多为 PostgreSQL。要验证迁移在 PostgreSQL 上正确执行可按文档步骤操作进入sandbox/目录并激活虚拟环境运行辅助脚本$ ./test_migrations.sh该脚本在 sandbox/test_migrations.sh 中实现它启用set -e与set -o pipefail保证任何一步失败立即中断然后执行./manage.py migrate --noinput --settingssettings_postgres即使用 sandbox/settings_postgres.py 中定义的 PostgreSQL 数据库配置重建 Oscar 数据库并完成全部迁移。脚本开头会输出Running migrations against Postgres便于确认执行阶段。仓库中还提供了make test_migrations目标先安装requirements_migrations.txt中的依赖再调用该脚本以及 sandbox/test_migrations.sh 对应的 CI 集成路径。三、报告 Bug 与请求特性高质量反馈的准则报告 Bug 与请求特性 一文强调在提交任何问题之前应遵循三条通用原则先在问题追踪器中搜索确认该 Bug 或特性请求是否已被提出过不要用追踪系统提问支持类问题这类问题应发到 django-oscar 邮件列表不要在追踪器中展开冗长讨论容易丢失。当某个 ticket 存在争议时请将讨论移到邮件列表进行。3.1 安全问题的上报渠道电商软件的安全至关重要Oscar 采用负责任披露responsible disclosure政策。如果你在 Oscar 或其扩展中发现疑似安全相关问题请通过邮件oscar.securitytangentlabs.co.uk报告核心团队会确认你的报告并采取相应措施——注意安全类问题不应走公开的 issue 追踪器。3.2 如何写出优秀的 Bug 报告一份结构良好的 Bug 报告价值极高文档给出了如下要点如果不确定所看到的现象是否真的是 Bug先在邮件列表上询问报告必须完整、可复现、具体包含清晰简洁的问题描述以及复现步骤尽可能多地附上调试信息如代码片段、测试用例、异常堆栈、截图等一个小而完整的测试用例是报告 Bug 的最佳形态它能让我们快速确认问题。3.3 UI 类 Bug 与视觉特性请求涉及视觉呈现的问题另有几条补充规范在 ticket 中附上截图把它当作「可视化的最小测试用例」——展示问题本身而不是你对浏览器做的各种自定义改动若你提交的 Pull Request 改变了 Oscar UI 的外观或行为请同时附上改动前和改动后的截图截图不能替代其他良好的报告习惯仍要提供 URL、代码片段和逐步复现说明。3.4 特性请求的最佳姿势特性请求是 Oscar 持续改进的动力最有效的提出方式是先在邮件列表上提出而不是直接进追踪器——在列表上会被更认真地阅读对于大规模特性尤其如此核心代码的大改动希望先经邮件列表讨论清晰、简洁地描述缺失的特性以及你期望的实现方式尽可能附上示例代码非可运行的伪代码也可以解释为什么需要该特性有时用途并不显而易见。正如大多数开源项目一样「代码会说话」。如果你愿意亲自实现该特性甚至已经写好了代码被接纳的概率会大得多。只需 Fork Oscar、创建特性分支并展示你的成果即可。四、编码规范让代码风格可预期Oscar 的编码规范 建立在三个外部规范之上PEP8Python 代码风格指南、PEP257Docstring 约定以及 Django 官方编码风格并推荐阅读《Code Like a Pythonista》。在「保持理性」的前提下请遵循以下约定。4.1 自动化风格检查make lintflake8 与 isort 用于强制基础编码标准一条命令即可运行全部检查$ make lint在当前仓库中Makefile 的lint目标实际包含三步用black --check排除migrations/目录检查src/oscar/与tests/的代码格式化再分别对setup.py、src/oscar/和tests/运行pylint。对应的详细规则可在 setup.cfg 中看到flake8段排除migrations忽略F405、W503、E731max-complexity为 10max-line-length为 119isort段line_length为 79使用括号换行use_parentheses true将oscar、tests标记为 first-party 模块并跳过*/migrations/*。此外 tox.ini 的lint环境还会执行npm ci、flake8 src tests setup.py、isort -c -q --diff、npm run eslint与django-admin.py compilemessages形成覆盖 Python、前端 JS 与翻译文件的完整静态检查链。4.2 URL 约定URL 设计直接影响 API 与页面地址的可预期性规范如下列表页使用复数形式如/products/、/notifications/详情页在列表页路径上追加主键/别名如/products/the-bible/、/notifications/1/创建页以create作为最后一个路径段如/dashboard/notifications/create/URL 名称使用连字符而非下划线更新页在 dashboard 场景下通常与详情页相同如/dashboard/notifications/3/若详情页与更新页需要区分则使用/dashboard/notifications/3/update/删除页如/dashboard/notifications/3/delete/。4.3 View 类命名视图类按%s%sView % (class_name, verb)的格式命名例如ProductUpdateView、OfferCreateView、PromotionDeleteView。该约定虽不能覆盖所有场景但是一个良好的基准你也可以在 dashboard 应用 的视图实现中找到大量遵循此命名模式的实际案例。4.4 引用管理器优先 _default_manager在代码中引用管理器时应使用_default_manager而非objects。这样允许项目覆盖默认管理器以提供领域特定行为是 Oscar 领域驱动设计风格在数据访问层的一个具体体现。4.5 HTML 缩进模板与 HTML 一律使用四个空格缩进。Oscar 的 241 个 HTML 模板位于 src/oscar/templates/oscar/编写或修改模板时请保持这一约定。五、提交 Pull Request避免失望的六个要点提交 Pull Request 篇幅不长但每一条都是实战经验为避免失望新特性应在投入大量工作之前先到邮件列表django-oscargooglegroups.com讨论编写测试未提供足够测试的 Pull Request 会被直接拒绝编写文档改变行为或引入新特性时必须同步更新文档写好提交信息可参考 Tim Pope 关于 Git 提交信息的经典建议首行是祈使语气的摘要正文说明「为什么」与「怎么做」除非另有指示Pull Request 应针对 Oscar 的master分支始终从自定义分支提交不要从自己的 master 分支提交。六、测试套件从单条用例到多版本矩阵Oscar 的测试体系在 测试套件文档 中有详尽说明它与仓库 tests/ 目录的 three-tier 结构一一对应。6.1 测试前置条件运行测试需要一个可用的 SQL 服务器PostgreSQL或 SQLite配合--sqlite参数Python 3.7 及以上版本。需要说明的是文档撰写时的最低版本要求是 python3.7而当前仓库的 tox.ini 已将测试矩阵更新为py{38,39,310,311,312,313}-django{42,52}即支持 Python 3.8 至 3.13、Django 4.2 与 5.2实际以你所用仓库分支的 tox 配置为准。6.2 最快路径make testOscar 使用 pytest 运行测试。最快的运行方式是$ make test该命令会先在venv中创建虚拟环境、安装测试依赖然后执行 pytest。Makefile 中的test目标依赖venv而venv目标使用python3 -m venv创建环境并安装.[test]扩展与docs/requirements.txt。6.3 手动分步运行想要完全掌控测试过程可以按文档的详细流程手动操作$ make venv $ source venv/bin/activate $ py.testpy.test是pytest命令的别名形式两者等价。你可以通过传入路径运行测试子集$ py.test tests/integration/offer/test_availability.py运行单个测试类注意双冒号::$ py.test tests/integration/offer/test_availability.py::TestASuspendedOffer运行单个测试方法$ py.test tests/integration/offer/test_availability.py::TestASuspendedOffer::test_is_unavailable按表达式匹配测试名$ py.test tests/integration/offer/test_availability.py -k is_unavailablepytest 的配置测试路径、忽略目录、警告过滤位于 setup.cfg 的[tool:pytest]段testpaths tests/norecursedirs .tox并对django_webtest.middleware与sorl.thumbnail.base的弃用警告做了过滤。6.4 多版本矩阵测试tox要针对多个 Django 与 Python 版本运行全部测试使用 tox$ toxtox 会按 tox.ini 的envlist展开矩阵py{38,39,310,311,312,313}-django{42,52}六个 Python 版本 × 两个 Django 版本django4.2,4.3与django5.2,5.3另有lint静态检查、sandbox构建沙箱站点与docs编译文档三个环境。运行前需要系统已安装对应版本的 Python 解释器其余依赖Django 等会由 tox 自动下载。为加快速度可以使用 tox 的并行模式。tox 环境的测试命令统一为coverage run --parallel -m pytest因此每次tox运行都会同时产出跨环境的覆盖率数据。6.5 测试的分类与命名测试按目录分为三类tests/integration/集成测试验证一组单元或一条链路的协作例如测试某个模板标签tests/functional/尽量接近「端到端」多数使用 WebTest 模拟用户浏览站点的行为tests/unit/从当前仓库目录结构可推断针对单一模块的单元测试。命名方面Oscar 使用pytest-specspec插件建议让测试类与方法名在 spec 输出中读起来通顺自然。例如$ py.test tests/integration/catalogue/test_product.py --spec运行后会输出如下可读性极强的报告以文档中的示例输出为参考tests/integration/catalogue/test_product.py::ProductCreationTests [PASS] Allow two products without upc [PASS] Create products with attributes [PASS] None upc is represented as empty string [PASS] Upc uniqueness enforced tests/integration/catalogue/test_product.py::TopLevelProductTests [PASS] Top level products are part of browsable set ... 15 passed in 15.39 seconds 仓库中还提供make retest仅重跑上次失败的测试对应pytest --lf与make coveragepytest --covoscar --cov-reportterm-missing生成覆盖率报告可作为日常迭代的高效补充。七、编写文档目录结构与构建方式编写文档 说明了 Oscar 文档体系的组织原则。文档由make docs构建当前要求python3构建工具链在 docs/Makefile 中定义而 docs/requirements.txt 提供 Sphinx 等构建依赖。文档全部位于docs/source/目录其结构是 Django 官方文档结构的简化版docs/source/internals/与 Oscar 自身相关的一切例如贡献指南或设计理念本篇所属目录docs/source/ref/参考文档其中ref/apps/是每个 Oscar 核心应用的指南说明其功能、主要模型、与其他应用的关系等docs/source/topics/「元」主题文章解释多个应用如何协同工作或 Oscar 如何与其他方案结合docs/source/howto/教程式文章讲解如何解决某个具体问题。docs/source/index.rst被设计为入口页面打破了上述结构以便让文档更易接近。其他index.rst只在文件过多、无法全部列出时才创建——例如docs/source/index.rst直接链接topics/与internals/的所有文件而howto/与ref/apps/各自拥有一个index.rst。风格方面Oscar 目前没有自己的文档风格指南撰写时请参考 Python 与 Django 的文档风格指南并务必使用性别中立的语言。八、完整协作流程图从想法到合并综合以上章节一次典型的 Oscar 贡献可以归纳为如下闭环构思与讨论在邮件列表上提出新特性/修复想法尤其涉及核心行为时搭建环境Fork 仓库 →git clone→make install可再make sandbox起本地站点验证写代码遵循 PEP8/PEP257 与 编码规范URL 约定、View命名、_default_manager、四空格缩进写测试按tests/integration/、tests/functional/、tests/unit/归类运行make test或py.test path验证必要时用tox跑完整矩阵写文档新增/改动行为时同步更新 docs/source/ 下对应文档用make docs验证构建静态检查运行make lint通过 black/pylint 检查提交与 PR从自定义分支提交而非 master写好提交信息针对master分支发起 Pull Request。结语参与 Oscar 贡献的完整路径——开发环境、Bug 报告、编码规范、PR 流程、测试矩阵与文档维护——在 docs/source/internals/contributing/ 目录下有系统性沉淀而 Makefile、tox.ini、setup.cfg 与 package.json 则为这条路径提供了自动化支撑。对于想要深入 Oscar 内部实现或为其贡献代码的开发者按本文流程走一遍即可从「使用者」平滑过渡到「贡献者」。赞分享后端电商【免费下载链接】django-oscarDomain-driven e-commerce for Django项目地址https://gitcode.com/gh_mirrors/dj/django-oscar点击查看免费下载相关推荐django-oscar 贡献指南从开发环境搭建、测试到提交 Pull Request 的完整参与流程django oscar 贡献指南从开发环境搭建、测试到提交 Pull Request 的完整参与流程 django oscar 是面向 Django 的领域后端电商chi 路由贡献指南从环境搭建、测试规范到 Pull Request 提交流程chi 路由贡献指南从环境搭建、测试规范到 Pull Request 提交流程 本文是 chi github.com/go chi/chi/v5 一个 l后端Web框架Dex 贡献指南从开发环境搭建到提交 Pull Request 的完整实战流程Dex 贡献指南从开发环境搭建到提交 Pull Request 的完整实战流程 本篇指南以 Dex基于 Go 的 OpenID Connect / OAut后端认证鉴权身份认证单点登录上一篇VoltageShift终极指南如何为Intel Macbook实现CPU/GPU降压降温下一篇POCO跨平台GUI主题实现代码基本主题示例创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考