记一次参与开源项目的过程

jQuery作为一款老牌js库，在DOM操作上依然有不错的优势，最近在认真演习jQuery源码，顺带写着一个专栏：《Js编程技巧之jQuery源码分析》，记录一下里面有用的技巧、写法和设计思想。在一次查阅API文档时，发现了一个问题，并尝试定位、解决此问题，提交了issue，本文在此记录一下。

发现问题

API文档里的错误截图（红色方框里）：

根据提示可以得知，由于回调函数可能返回两个参数，文档定义了两个参数类型：String或者Array，导致抛出了错误信息：ERROR: A single return element is expected

于是决定找出导致错误信息的地方，添加对多类型的支持，fix它。

追踪、解决问题

jQuery站点工程化的调研

经过一段时间对贡献说明文档的探索研究，发现了该项目的特点：

• jQuery有一套预定的wordpress实例（一整套解决方案，不需要开发者额外配置数据库），所有的jQuery Foundation的网站都采用该实例，实现可标准化。（不难发现这些网站结构比较类似）
• 该wordpress实例通过Vagrant+VM VirtualBox跑在虚拟容器里
• jQuery API站点通过grunt打包工具将编译后的文件搬到wordpress实例的相关目录下

流程图如下：

定位问题

观察源码，根据错误信息定位到grunt编译打包过程，XML的编译是由一个名为grunt-jquery-content的npm包实现的，定位到这个package里的entries2html-base.xsl文件,该文件负责将xml编译为html文件.
决定做以下修改：
由

	
	
		
			
				ERROR: A single return element is expected
			
			
		
	

改为

	
		
			
				 | 
			
			
		
	

修改的效果如下：

完美解决问题！

• xml的依赖库安装:libxml2-2.7.8.win32、iconv-1.9.2.win32、zlib-1.2.5、libxslt-1.1.26.win32,下载地址，并设置环境变量。用于解析或编译xml文件。x64电脑必须下载win32版本。
• Vagrant启动缓慢（需要梯子并在网速空闲时下载依赖资源）
• 需要配置一下本机的hosts文件里域名到IP的映射，文件目录为：C:\Windows\System32\drivers\etc\hosts

提出issue

然后就是到官方的github仓库，提出issue：

截至到发稿日期，该issue尚未得到官方的回应，看来jQuery社区已经不再活跃，但无论如何，这次参与对我而言都是非常有意义的。

总结

• windows平台总体还是比较鸡肋，特别是一些第三方库的安装和支持不太好（尽可能使用mac工作）
• jQuery本地开发环境通过Vagrant+VM VirtualBox跑在本机的虚拟容器里，保证了开发与部署环境的一致性，抹平的平台差异。这点让我感觉惊艳，学习到了虚拟容器技术给开发部署带来的便利
• 提issue时，要有一个负责的心态，提供详细、准确的英文表达，描述你发现的问题，以及你如何尝试并解决了这个问题。