在最后几天,我问自己如何从git的commit / tag消息中获得的信息生成发行说明。
决定
我的第一种方法是直接从提交消息创建更改列表,但是这种方法有很多缺点。
- 提交消息必须写得非常严格
- 需要一个标记来收集属于发行版的消息(通常的标记就足够了)
- 提交消息的内容必须遵循约定,以便功能 , 错误修正和更改可以收集并在一个块中显示
因此,我使用带注释的标签,该标签必须提供带有标签的消息。 使用git创建它们相当容易
git tag -a v.1.0.0 -m "This is an annotated tag"
旁注:这种标签有一个不错的补充,它允许检查哪些提交属于特定标签。
下一个决定是关于消息应使用的标记语言。 因为我是markdown的粉丝,所以决定这么做。 这将导致人类可读的消息以及众所周知且有效的解析。
重要提示
Git通常将#解释为注释的开始。 如果您要使用的头标和第二头标以上,则必须使用选项–cleanup = verbatim创建带注释的标签,以禁止使用此功能。
通过这个决定,我开始在gradle中实现一个小示例,该示例在构建过程中创建发行说明。 在下一节中,我向您展示所需的代码
实作
先决条件
因为我也想要发行说明的漂亮版本,所以我决定将markdown直接转换为html页面。 为此,我将PegDown用作Markdown处理器,并使用带有bootswatch主题的twitter bootstrap来对输出进行样式设置。
初始构建脚本
buildscript {
repositories {
mavenCentral()
mavenLocal()
}
dependencies {
classpath 'org.pegdown:pegdown:1.4.1'
}
}
import org.pegdown.PegDownProcessor
import groovy.text.SimpleTemplateEngine
实施逻辑
我们首先要控制生成发行说明的过程
task releaseNotes() { def releaseNotes = new File('releaseNotes.md') releaseNotes.delete() def versions = "" def tags = readTags() tags.each {tag -> versions += "- [$tag](#$tag)\n" } tags.each {tag -> releaseNotes << "# ${tag}\n" def message = readTagMessage(tag) message.each{releaseNotes << "$it\n"} releaseNotes << "\n" } def writer = new StringWriter() def pdp = new PegDownProcessor() def engine = new SimpleTemplateEngine() def template = engine.createTemplate(new File("releaseNotes.tpl")) def daten = [releaseNotes:pdp.markdownToHtml(new File("releaseNotes.md").text), application: project.name, versions:pdp.markdownToHtml(versions)] def ergebnis = template.make(daten) new File('releaseNotes.html').withWriter { w -> w.write(ergebnis) } }
这个过程真的很简单。
- 首先,我们清理降价文件的旧工件(第2行和第3行)。 之后,我们创建了Versions部分,并加载可用的标签(第5至10行),并将所有内容放入一个单独的列表中。
- 然后,我们创建有关发行说明的信息,并为每个标签添加标题,然后添加属于该标签的消息(第12至18行)。
- 作为最后一步,我们解析markdown文件并通过将解析后的值传递给模板来创建html页面。
如您所见,还需要三个组件
- readTags方法
- readTagMessage方法
- html页面的模板
readTags
该方法调用:
git tag -l
并返回标签的反向排序列表
def readTags() {
def tags = []
def proc = "git tag -l".execute()
proc.in.eachLine { line -> tags += line}
tags.sort {}
Collections.reverse( tags )
tags
}
readTagMessage
该方法使用
def readTagMessage(String tag) {
def message = []
def proc = "git cat-file tag $tag".execute()
def startCollection = false
proc.in.eachLine { line ->
if (line.isEmpty()) {
startCollection = true
}
if (startCollection) {
message += line
}
}
proc.err.eachLine { line -> println line }
message
}
releaseNotes.tpl
该模板包含三个属性应用程序, releaseNotes和版本 。 应用程序将替换为您的应用程序名称,并在标题中使用。 releaseNotes包含转换后的发行说明。 最后, 版本代表:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang='de' xmlns='http://www.w3.org/1999/xhtml' lang='de'>
<head>
<title>Release Notes of $application</title>
<link rel="stylesheet" href="http://bootswatch.com/yeti/bootstrap.min.css">
<link rel="stylesheet" href="http://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">
<style type="text/css">
.releasenotes h1 {
font-size: 1.5em;
}
.releasenotes h2 {
font-size: 1.2em;
}
</style>
</head>
<body>
<div class="row">
<div class="navbar navbar-default">
<div class="col-md-4"></div>
<div class="col-md-4">
<h1>Releasenotes</h1>
</div>
<div class="col-md-4"></div>
</div>
</div>
<div class="row releasenotes">
<div class="col-md-4"></div>
<div class="col-md-4">$releaseNotes</div>
<div class="col-md-4"><h1>Versions</h1>$versions</div>
</div>
<script src="http://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
</body>
</html>
如先决条件中所述,twitter引导程序和bootswatch的主题将用于美化代码。
最后
将所有内容放在一起后,我们可以创建一个带注释的标签并简单地调用
gradle releaseNotes
gradle将读取所有消息和标签并创建两个文件
- releaseNotes.md和
- releaseNotes.html( 示例 –感谢我的一位同事对这个版本的布局和设计的想法)
结论
通过这个简单的构建脚本和一些约定,我们可以从存储库信息中创建发行说明。 此外,由于所有内容都直接存储在存储库中,因此我们不必维护发行说明的多个位置。
通过使用Markdown,我们可以使用简单的标记和人类可读的标记语言,使我们能够为Web应用程序创建漂亮的发行说明。 像我在本示例中一样,可以将markdown信息直接解析到html页面,但是您也可以提供简单的markdown文件,并在客户端或服务器上的交付时解析它。
- 与往常一样,完整的代码可在github https://github.com/coders-kitchen/tut-releaseNotesFromTags上找到。