阅读 370

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

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文件. 决定做以下修改: 由

	<!-- a return element -->
	<xsl:if test="return">
		<xsl:for-each select="return">
			<xsl:if test="position() &gt; 1">
				<strong>ERROR: A single return element is expected</strong>
			</xsl:if>
			<xsl:call-template name="render-types"/>
		</xsl:for-each>
	</xsl:if>
复制代码

改为

<!-- a return element -->
	<xsl:if test="return">
		<xsl:for-each select="return">
			<xsl:if test="position() &gt; 1">
				<span> | </span>
			</xsl:if>
			<xsl:call-template name="render-types"/>
		</xsl:for-each>
	</xsl:if>
复制代码

修改的效果如下: 在这里插入图片描述 完美解决问题!

  • xml的依赖库安装:libxml2-2.7.8.win32iconv-1.9.2.win32zlib-1.2.5libxslt-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时,要有一个负责的心态,提供详细、准确的英文表达,描述你发现的问题,以及你如何尝试并解决了这个问题。
文章分类
前端
文章标签