Orekit教程发布指南

本发布指南主要参考自Orekit发布指南

请注意:

前提条件

  • 获取Orekit签名密钥的私钥,密钥ID:0802AB8C87B0B1AEC1C1C5871550FDBD6375C33B

如果需要帮助,请在Orekit论坛的开发部分提问。

使用mvn -ep命令为Orekit签名密钥生成加密密码。

验证develop分支的状态

在进行任何操作之前,请在持续集成页面上检查develop分支的状态是否正常。

还要在本地仓库上检查develop分支的质量是否良好:不应该有Maven、Java、Javadoc、Checkstyle和SpotBugs的错误或警告。如果有,请先修复警告和错误!

要进行此检查,请检查本地IDE中的Checkstyle和Java错误。
然后运行SpotBugs、Java、Javadoc和Checkstyle检查:

mvn clean javadoc:javadoc verify site

首先查看此命令的日志,确保没有错误。

然后从./target/site/index.html页面开始浏览生成的网站,并在底部检查Checkstyle和SpotBugs报告。

准备发布的Git分支

发布将在专用分支上进行,而不是直接在主分支或develop分支上进行。
因此,必须创建一个新分支,并用于其他所有操作:

git branch release-X.Y
git checkout release-X.Y

更新maven插件版本

发布是更新Maven插件版本的好机会。它们都集中在一个地方,在orekit-tutorials/pom.xml中的一组属性中:

<!-- 项目特定的插件版本 -->
<orekit-tutorials.spotbugs-maven-plugin.version>3.1.12</orekit-tutorials.spotbugs-maven-plugin.version>
<orekit-tutorials.maven-changes-plugin.version>2.12.1</orekit-tutorials.maven-changes-plugin.version>
<orekit-tutorials.maven-checkstyle-plugin.version>3.1.0</orekit-tutorials.maven-checkstyle-plugin.version>
...

您可以使用http://search.maven.org/#search上的搜索功能找到插件的最新版本。所有属性的命名都遵循orekit-tutorials.some-plugin-name.version的模式,应该在Web表单中使用插件名称来检查可用版本。

请注意,在某些情况下,由于不兼容性,无法使用最新版本。例如,当插件最近没有更新并且与其依赖项的较新版本发生冲突时。

还要注意,某些插件使用可能需要更新的配置文件。这通常是maven-checkstyle-pluginspotbugs-maven-plugin的情况。可能需要检查/checkstyle.xml/spotbugs-exclude-filter.xml文件。

在提交这些更改之前,您必须检查一切是否正常运行。因此,请运行以下命令:

mvn clean
LANG=C mvn clean javadoc:javadoc site

如果出现问题,请通过更改插件配置来修复问题,或者回滚到插件的早期版本。

target/site/index.html页面开始浏览生成的站点,并检查是否正确呈现所有内容。

当一切顺利且生成的站点正常时,您可以提交更改:

git add pom.xml checkstyle.xml spotbugs-exclude-filter.xml
git commit -m "更新maven插件版本。"

更新changes.xml

完成文件/src/changes/changes.xml

发布日期和描述通常在开发过程中仅设置为TBD,必须设置为适当的值。

用描述版本的文本替换TBD描述,列出版本引入的主要功能等(请参阅以前版本的描述示例)。

提交changes.xml文件。

git add src/changes/changes.xml
git commit -m "为正式发布更新changes.xml。"                                                        

更改库版本号

pom.xml文件包含库的版本号。在开发过程中,该版本号的形式为X.Y-SNAPSHOT。发布时,必须删除-SNAPSHOT部分。

如果您正在发布教程,这意味着Orekit的新版本刚刚发布。
因此,您还应该在orekit.version变量中更改Orekit版本号。
从:

<orekit-tutorials.orekit.version>X.Y-SNAPSHOT</orekit-tutorials.orekit.version>

到:

<orekit-tutorials.orekit.version>X.Y</orekit-tutorials.orekit.version>

提交更改:

git add pom.xml
git commit -m "Dropped -SNAPSHOT in version number for official release."

标记和签署git存储库

当完成所有前面的步骤后,本地git存储库保存了发布的源代码和构建文件的最终状态。
必须对其进行标记并签署。
使用以下命令进行标记和签署:

git tag X.Y -s -u 0802AB8C87B0B1AEC1C1C5871550FDBD6375C33B -m "Version X.Y."

可以使用以下命令验证标记:

git tag -v X.Y

推送分支和标记

当标记准备好后,必须将分支和标记推送到Gitlab,以便每个人都可以进行审查:

git push --tags origin release-X.Y

等待持续集成作业运行,并检查在release-X.Y分支上是否一切正常。

Maven网站

使用以下命令在本地生成Maven网站:

LANG=C mvn clean site

Orekit网站的Maven网站部分在将工作合并到developrelease-*master分支时会自动更新。

在本地生成签名的构件

与Orekit库不同,Orekit教程构件不会被推送到Sonatype OSS网站。
构件只需要在本地生成,然后上传到Gitlab forge。要在本地生成签名的构件(以及再次生成网站),运行以下命令:

mvn clean verify site install -Prelease

在生成过程中,Maven将触发gpg,要求用户输入访问签名密钥的密码。
Maven没有提示我,所以我不得不添加-Dgpg.passphrase=[密码]

命令结束后,检查./target目录中是否包含预期的构件及其关联的签名和校验和文件:

  • orekit-tutorials-X.Y.pom
  • orekit-tutorials-X.Y.jar
  • orekit-tutorials-X.Y-sources.jar
  • orekit-tutorials-X.Y-javadoc.jar

签名和校验和文件的名称类似,添加了扩展名.asc

将发布分支合并到主分支

release-X.Y分支合并到master分支,以包含所做的任何更改。主分支始终包含库的最新发布版本。

git checkout master
git merge --no-ff release-X.Y

将主分支合并到开发分支

将更新的master分支合并到develop分支,以包含所做的任何更改。

git checkout develop
git merge --no-ff master

在开发分支中准备下一个开发周期

更新develop分支上的版本号,以准备下一个开发周期。
编辑pom.xml版本(包括Orekit教程和Orekit变量)为SNAPSHOT,并在./changes/changes.xml中为新更改留出空间。
然后提交并推送。

将构件上传到Gitlab

在Gitlab中,导航到Self > Settings > Access Tokens。输入名称、日期,并勾选“api”框,然后点击“Create personal access token”。
将令牌复制到以下命令中:

for f in $( ls target/orekit-tutorials-X.Y*.jar{,.asc} ) ; do
    curl --request POST --header "PRIVATE-TOKEN: <token>" --form "file=@$f" \
        https://gitlab.orekit.org/api/v4/projects/35/uploads
done

复制打印出的URL。

接下来,导航到Projects > Orekit > Repository > Tags。找到X.Y标签,点击编辑按钮输入发布说明。粘贴从上一步复制的URL。

导航到Projects > Orekit > Releases,确保显示正常。

关闭X.Y里程碑

在Gitlab中,导航到Projects > Orekit > Issues > Milestones。如果存在与发布X.Y对应的行,请点击“Close Milestone”。