====== 使用 MC-Publish 将模组发布到 Curseforge、Modrinth 和 Github ======

:!: **本页翻译自 [[tutorial:publishing_mods_using_github_actions]]，如有过时的地方可参考原文。**

MC-Publish 是一个 GitHub action，由 Kir-Antipov 制作，可以在 GitHub、CurseForge 和 Modrinth API 中交互，以上传您的模组文件。本页面会大致描述基本的设置过程，你需要 [[https://github.com/Kir-Antipov/mc-publish#publish-minecraft-mods---github-action|阅读 GitHub 文档以了解详细信息。]]

===== 什么是 GitHub Actions? =====

[[https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions|Github Actions]] 本质上是由 GitHub 服务器执行的命令，可以免费试用，只要你的 GitHub 存储库是公开的，且有限制，如果不是那么就不会妨碍您的使用。在软件开发中，Github Actions 和类似的工作流自动化系统是标准场所，并且极大地帮助您使得部署过程（例如发布新版本的模组）尽可能无缝衔接。

如果您不愿手动将您的模组上传到多个平台上，那么这就是解决方案。

===== 开始之前 =====

您需要已完成以下操作：
  - 在 GitHub 上，创建您的模组的存储库
  - 将您的模组的一个版本上传到 Curseforge 和 Modrinth 上并且被批准


===== 设置 =====

如果需要让 GitHub 为我们做点什么，我们需要告诉服务器，我们到底需要什么。因此，我们需要在 ''/.github/workflows'' 中创建一个 ''.yml'' 文件。你可以将这个 ''.yml'' 文件想象成您的 GitHub Action 的配置文件。文件的命名方式不重要，但您应该选择一个相关的名称。YAML 的概念与 JSON 的类似，但是语法不同。就像 Python 那样，你不需要使用花括号 ''{}''，而只需要使用缩进来声明你的结构。

你的 ''.yml'' 文件的基本结构看上去应该像这样：

<code yaml>
name: 发布到 Github、Curseforge 和 Modrinth    #你的 github.com 上的 GitHub Action 的名称
 
on: [ pull_request, workflow_dispatch ]           #何时执行你的 GitHub Action，'pull_request' -> 在每次合并（拉取）请求，'workflow_dispatch' -> 允许通过 github.com 手动执行

env:                                              #环境变量，后续可以使用 ${{ env.MINECRAFT_VERSION }} 引用，可以用作重复的信息并允许后续模组新的更新中快速更改
  MINECRAFT_VERSION: 1.19.2                        
  JAVA_VERSION: 17                   

permissions:
  contents: write

jobs:                                             #在这里你就会实际告诉 GitHub 的服务器需要做什么
  build:                                          #要发布你的模组，你只需要一个 job，这里称为 build。
    runs-on: ubuntu-latest                        #'runs-on' 指定了操作系统（linux）。
    steps:                                        #在 'steps' 中你会列举出所有单独的命令，例如 Kir-Antipov 的 MC-Publish。
      ...
</code>

我建议保持 ''on: [ pull_request, workflow_dispatch ]'' 并相应地使用 git 分支。这意味着，在每个分支上开发自己的更新，并在准备发布的时候合并到主分支中。如果这个确实无法满足你的需求，可以[[https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows|检查不同的触发]]或者直接使用 ''workflow_dispatch''。记住，设置的时候你不需要意外地运行你的 GitHub Action。

基本的环境变量应该包括：
  * Minecraft 版本
  * Java 版本
  * 你的模组版本
  * 你的模组发行名称
  * 发布令牌（后面讲到）

==== 发布步骤 ====

这可以说是你的 ''.yml'' 文件中最重要的部分！

首先我们需要看看一个步骤的语法，准备所有的先行步骤，然后在走 MC-Publish。

=== 语法 ===

<code yaml>
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 示例设置
        if: ${{ condition is met }}
        uses: actions/common-action
        with: 
          variable1: 一些值
          variable2: 另一些值
        run: ls -a
        
      - name: 另一个示例设置
       
        ...
</code>
   * ''name'' 步骤的名称，应该准确描述该步骤。
   * ''if'' 需要返回 true 的条件，符合条件才执行步骤。
   * ''uses'' 这里你可以指定额外的 GitHub Action。你应该自己编写一切，但如果已经有人帮你写好了呢？Kir-Antipov 的 MC-Publish 就是其中一个例子。
   * ''with'' 如果你指定 GitHub Action 时使用了 ''uses''，你可以输入预先定义的变量以及各自的值。
   * ''run'' 在命令行中执行命令。

=== 先行步骤 ===

以下步骤复制了你能够在电脑上开发模组之前需要完成的步骤，就想象一下你是一个简单的 linux 服务器，突然有人想要你上传他们的 minecraft 模组，你甚至不知道 Java 是什么。

<code yaml>
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检查环境变量
        run: env

      - name: 签出存储库
        uses: actions/checkout@v3
        with:
          submodules: true

      - name: 设置 Java
        uses: actions/setup-java@v2
        with:
          distribution: "temurin"
          java-version: 17

      - name: 使 Gradle Wrapper 可执行
        if: ${{ runner.os != 'Windows' }}
        run: chmod +x ./gradlew

      - name: 构建
        run: ./gradlew clean build
        
        ...
</code>

虽然上面这些步骤是必要的，但是你不需要完全理解。如果你有兴趣想要完全理解的话，我建议你入门 linux。

执行“Build”步骤可能要最长时间（大概 3 分钟），所以不要担心是否出错，出错了会提示的。

=== MC-Publish ===

本段落本质上并不完整，如要有全面的了解可以 [[https://github.com/Kir-Antipov/mc-publish#publish-minecraft-mods---github-action|检查 MC-Publish 的官方 GitHub 文档]]。 

<code yaml>
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      ...
      
      - name: 发布（CurseForge/Modrinth/Github）
        uses: Kir-Antipov/mc-publish@v3.2                                   #指定 MC-Publish Github Action 版本 3.2
        with:
          curseforge-id: 123456                                             #你的 curseforge 项目的 id
          curseforge-token: "${{env.CURSEFORGE_TOKEN}}"
          
          modrinth-id: 1q2w3e4r                                             #你的 modrinth 项目的 id
          modrinth-token: "${{env.MODRINTH_TOKEN}}"
          
          github-tag: "v${{env.VERSION}}"
          github-token: "${{env.GITHUB_TOKEN}}"

          name: "${{env.RELEASE_NAME}}"                             
          version: "${{env.VERSION}}"
          version-type: release
          changelog-file: CHANGELOG.md                                      #指定新更新的内容的文件（路径从项目根目录开始）

          loaders: fabric
          game-versions: "${{env.MINECRAFT_VERSION}}"
          java: "${{env.JAVA_VERSION}}"
</code>

''CURSEFORGE_TOKEN''、''MODRINTH_TOKEN'' 和 ''GITHUB_TOKEN'' 本质上是用来验证你自己的密码，这意味着对应了你的账号，而不是你的模组。这可以确保只有你能通过 API 来推送更新。当你正常上传的时候，你会在登录的时候验证自己。在哪里找到这些令牌呢？每个平台有不同的步骤：

**//Github//** Settings > Developer Settings > Personal access tokens > Tokens (classic) => 按 "Generate new token" and choose classic => select the 'repo' scope (write a descriptive note, 90 days
expiration is recommended, you will need to generate a new token afterwards) => 按"Generate token"

**//Modrinth//** Settings => Authorization token 

**//Curseforge//** Settings > My API Tokens => 选择一个描述性的名称并点击 "Generate Token"   

It is **strongly recommended** that you save the authentication tokens somewhere safe, e.g. a password manager. **Github //won't// let you access your token after you have generated it!**
**强烈建议**将这些令牌存储在安全的地方，例如密码管理器。**GitHub//不会//在你生成之后让你访问这些令牌！**


现在你有了需要的所有令牌，你需要让 GitHub Action 能够访问这些令牌。到你的 GitHub 模组存储库的 Settings 页面，并前往 Secrets > Actions。将所有的令牌添加为 secrets。你需要在你的 ''.yml'' 文件中引用你在这里提供的名称。例如，命名为 ''PUBLISH_CURSEFORGE_TOKEN'' 的 secret 可以这样引用：
<code yaml> 
${{ secrets.PUBLISH_CURSEFORGE_TOKEN }}
</code>


==== 完整的 .yml 例子 ====
<code yaml>
name: 发布到 Github、Curseforge 和 Modrinth    
 
on: [ pull_request, workflow_dispatch ]           

env:                                              
  MINECRAFT_VERSION: 1.19.2                        
  JAVA_VERSION: 17      
  VERSION: 1.1.0+1.19.2  
  RELEASE_NAME: 用于 Minecraft 1.19.2 的示例模组 1.1.0
  MODRINTH_TOKEN: ${{ secrets.PUBLISH_MODRINTH_TOKEN }}
  CURSEFORGE_TOKEN: ${{ secrets.PUBLISH_CURSEFORGE_TOKEN }}
  GITHUB_TOKEN: ${{ secrets.PUBLISH_GITHUB_TOKEN }}           

permissions:
  contents: write

jobs:                                             
  build:                                          
    runs-on: ubuntu-latest                        
    steps:                                        
      - name: 检查环境变量
        run: env

      - name: 签出存储库
        uses: actions/checkout@v3
        with:
          submodules: true

      - name: 设置 Java
        uses: actions/setup-java@v2
        with:
          distribution: "temurin"
          java-version: 17

      - name: 使 Gradle Wrapper 可执行
        if: ${{ runner.os != 'Windows' }}
        run: chmod +x ./gradlew

      - name: 构建
        run: ./gradlew clean build
        
      - name: 发布（CurseForge/Modrinth/Github）
        uses: Kir-Antipov/mc-publish@v3.2                                   
        with:
          curseforge-id: 123456                                             
          curseforge-token: "${{env.CURSEFORGE_TOKEN}}"
          
          modrinth-id: 1q2w3e4r                                             
          modrinth-token: "${{env.MODRINTH_TOKEN}}"
          
          github-tag: "v${{env.VERSION}}"
          github-token: "${{env.GITHUB_TOKEN}}"

          name: "${{env.RELEASE_NAME}}"                             
          version: "${{env.VERSION}}"
          version-type: release
          changelog-file: CHANGELOG.md                                      

          loaders: fabric
          game-versions: "${{env.MINECRAFT_VERSION}}"
          java: "${{env.JAVA_VERSION}}"
</code>

===== 设置完成 =====

回顾一下，这是您现在应该拥有的：
  * Wie每个平台新生成的验证令牌
  * 验证令牌存储在你的 GitHub 存储库的 secrets 中
  * 在 ''/.github/workflows'' 的一个 ''.yml'' 文件，并推送到你的 GitHub 存储库中
  * 你的项目根目录中的空白 ''CHANGELOG.md'' 文件

如果你拥有所有这些，你就完成了！您现在可以使用新创建的 Github Action 为您的模组部署更新！

===== 额外步骤 =====

以下是不适合一般教程的有用资源列表。

==== 更新检查列表 ====
更新你的模组时，你需要看看的几个地方。
  * 更新版本号
     * 在 ''src/fabric.mod.json''，中，在 ''"version": "1.1.0+1.19.2"''
     * 在 ''gradle.properties''（通常情况），在 ''mod_version = 1.1.0+1.19.2''
     * 在 ''.github/workflows/publish.yml'' 在 ''VERSION: 1.1.0+1.19.2'' 和 ''RELEASE_NAME: 用于 Minecraft 1.19.2 的示例模组 1.1.0''
  * 更新 ''CHANGELOG.md'' 中的更新记录
  * （如果你使用推荐的工作流程）将更新分支合并到当前默认分支


==== 处理依赖 ====

[[https://github.com/Kir-Antipov/mc-publish#dependencies|请检查官方文档]]。我建议使用 ''fabric.mod.json'' 方法。

==== 上传到 Modrinth 的错误 ====

由于 Modrinth 更新了 API，一些人可能在通过这些 API 上传时会遇到问题，这种情况下可以将 modrinth 的部分从 GitHub 和 Curseforge 分开。你可以复制 MC-Publish 步骤并删除 ''with'' 中的现在不必要的输入部分来轻松完成此操作。你现在应该有两个独立的步骤。

将发布到 modrinth 的步骤的版本更改为 2.1 -> ''uses: Kir-Antipov/mc-publish@v2.1''