Ziggy项目贡献指南与技术规范解析

Ziggy项目贡献指南与技术规范解析

ziggy Use your Laravel routes in JavaScript. 项目地址: https://gitcode.com/gh_mirrors/zi/ziggy

项目概述

Ziggy是一个优秀的JavaScript路由工具，专为现代Web应用设计。它能够将后端路由无缝地传递到前端JavaScript环境中，实现前后端路由的统一管理。作为开源项目，Ziggy欢迎开发者参与贡献，但需要遵循一定的技术规范和流程。

技术贡献流程详解

1. 问题验证与功能讨论

在提交问题报告或功能请求前，开发者应当：

• 完整复现问题场景，确认问题确实存在
• 全面检查现有功能，避免重复建议
• 查阅现有工作列表，确认没有相同建议在进行中

对于新功能建议，项目维护团队更倾向于先进行技术讨论，而非直接提交代码。这种方式可以确保：

• 功能设计符合项目整体架构
• 避免重复开发工作
• 获得维护团队的技术指导

2. 代码提交规范

提交Pull Request前需要：

• 彻底检查代码库，确认功能尚未实现
• 审查现有Pull Request，避免重复工作
• 确保每个Pull Request只包含一个独立功能

测试体系解析

Ziggy项目采用完善的测试体系保障代码质量：

PHP测试环境

• 使用Orchestra Testbench作为测试框架
• 采用Pest作为PHP测试工具
• 测试命令：vendor/bin/pest

JavaScript测试环境

• 使用Vitest测试框架
• 测试命令：npm test

特殊注意事项

Windows开发者可能会遇到CRLF换行符问题，解决方案：

git config --global core.autocrlf input

此配置确保Git克隆时保留原始换行符。

TypeScript类型系统维护

Ziggy项目包含手动维护的TypeScript类型定义，测试方法如下：

1. 打开tests/js/types.ts文件
2. 该文件包含Ziggy的route()函数使用示例
3. 添加测试用例时：
   • 对于预期正常工作的代码，添加注释说明
   • 对于预期会报错的代码，添加// @ts-expect-error注解

版本发布流程详解

Ziggy项目采用双发布机制，同时发布到Packagist和NPM平台，流程如下：

1. 版本号更新

   • 使用命令更新版本号：npm version <version> --no-git-tag-version
   • 注意版本号不带"v"前缀

2. 文档更新

   • 更新变更日志(Changelog)

3. 构建流程

   • 执行构建命令：npm run build

4. 代码提交

   • 提交到对应分支(如2.x或main)

5. 发布流程

   • 创建GitHub发布，标签名带"v"前缀
   • 预发布版本需标记为pre-release，并发布到NPM的next标签

代码规范要求

1. 编码风格

   • 严格遵循PSR-2编码标准
   • 推荐使用PHP Code Sniffer工具检查

2. 代码质量

   • 遵循Tighten特定代码风格(Tlint)
   • 虽然Tlint主要面向应用开发，但仍建议运行检查

3. 开发原则

   • 单一职责原则：每个Pull Request只实现一个功能
   • 清晰提交：保持提交历史的整洁和可读性

技术协作建议

1. 保持友善的交流态度
2. 复杂功能先讨论后实现
3. 充分利用现有测试框架
4. 遇到技术问题及时寻求帮助

通过遵循这些规范，开发者可以更高效地为Ziggy项目贡献代码，同时确保项目保持高质量的技术标准。

ziggy Use your Laravel routes in JavaScript. 项目地址: https://gitcode.com/gh_mirrors/zi/ziggy