Update Package References, README, and GitHub Templates (#6)

* Update README * Update package references and typst.toml * New: GitHub templates * Update docs & feat request templates * Update: Automaticly generate package-releasing-ready version * Update: add guide and note for updating the package-release patch --------- Co-authored-by: 张尧 <[email protected]>
TJ-CSCCG · Jun 22, 2024 · c6414b8 · c6414b8
1 parent 32285d3
commit c6414b8
Show file tree

Hide file tree

Showing 20 changed files with 317 additions and 89 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,45 @@
+---
+name: Bug 反馈
+about: 通过该 Issue 模板反馈使用 tongji-undergrad-thesis-typst 时的 bug
+labels: 'type/bug'
+---
+
+### 使用平台详情
+
+<!--在你所使用的平台上打勾，或填写你使用的平台-->
+
+* [ ] 线上：Typst App
+* [ ] 本地：Typst
+* [ ] 不，我使用的是 _________
+
+<!--此外，建议你在下方详细描述你所使用的工具，如编辑器与编译器类型等等-->
+
+### 编译日志
+
+<!--在下方贴出编译时输出的错误日志-->
+
+<details><summary><b>报错内容</b> <i>[点击打开]</i></summary>
+<div>
+
+```log
+# Paste your log here:
+```
+
+</div>
+</details>
+
+### 文件结构
+
+<!--如果你修改了项目文件结构（例如：将 bib 文件从 bib 目录移出），还请在下方给出当前目录树。如果没有修改的话，还请删除本小节-->
+
+```log
+
+```
+
+### 问题描述
+
+<!--在下方填写你认为可能存在的问题。如果可以的话，还希望你能够给出你的建议和修改意见-->
+
+### 其他信息
+
+<!--这里用于写有关于上述 bug 的其他信息-->
diff --git a/.github/ISSUE_TEMPLATE/docs_request.md b/.github/ISSUE_TEMPLATE/docs_request.md
@@ -0,0 +1,25 @@
+---
+name: Docs 反馈
+about: 通过该 Issue 模板反馈目前 tongji-undergrad-thesis-typst 文档的不足之处
+labels: 'type/docs'
+---
+
+### 文档不足之处
+
+<!--在你认为存在缺陷的部分打勾-->
+
+* 平台相关
+  * [ ] 在线平台：Typst App
+  * [ ] 本地平台：Typst
+* 使用过程
+  * [ ] 模版编译（编译配置、依赖安装等）
+  * [ ] 最佳实践（Typst 基础知识、模版使用教学、工作流等）
+* [ ] 不，我需要其他文档：_________
+
+### 对文档的期望
+
+<!--如果可以的话，还希望你能够在下方提供你期望中的文档大纲-->
+
+### 其他信息
+
+<!--这里用于写有关于上述 docs 的其他信息-->
diff --git a/.github/ISSUE_TEMPLATE/feat_request.md b/.github/ISSUE_TEMPLATE/feat_request.md
@@ -0,0 +1,21 @@
+---
+name: Feature 建议
+about: 通过该 Issue 模板反馈向 tongji-undergrad-thesis-typst 提供需要新增的 feature 的具体信息
+labels: 'type/feature'
+---
+
+### 新增特性类型
+
+<!--点选下方的特性类型-->
+
+* [ ] 构建相关（如需要提供新的构建方法，现有构建方式需要迭代重构等）
+* [ ] 模板功能相关（如需要模板提供其他实用功能，适配新的模板样式等）
+* [ ] 文档相关（如更好展现该模板使用方法的想法）
+
+### 特性描述
+
+<!--在这里描述新增特性本身及其重要性。如果可能的话，还希望能够描述新增特性的实现方案-->
+
+### 其他信息
+
+<!--这里用于写有关于上述特性的其他想法-->
diff --git a/.github/bin/package_release.sh b/.github/bin/package_release.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+MAIN_BRANCH="main"
+PACKAGE_RELEASE_BRANCH="package"
+PACKAGE_RELEASE_DIFF=".github/patches/package_release.diff"
+
+set -e
+
+git branch -D $PACKAGE_RELEASE_BRANCH || true
+
+git checkout -b $PACKAGE_RELEASE_BRANCH origin/$MAIN_BRANCH
+
+git apply $PACKAGE_RELEASE_DIFF
+
+git add .
+
+git commit -m "Applied package releasing patch to \`main\` branch"
+
+git push origin $PACKAGE_RELEASE_BRANCH --force
+
diff --git a/.github/patches/package_release.diff b/.github/patches/package_release.diff
@@ -0,0 +1,56 @@
+diff --git a/init-files/main.typ b/init-files/main.typ
+index 9d382fa..7ae7825 100644
+--- a/init-files/main.typ
++++ b/init-files/main.typ
+@@ -1,2 +1,2 @@
+-#import "../paddling-tongji-thesis/tongjithesis.typ": *
++#import "@preview/paddling-tongji-thesis:0.1.1": *
+
+diff --git a/init-files/sections/01_intro.typ b/init-files/sections/01_intro.typ
+index 11a6b70..3b71298 100644
+--- a/init-files/sections/01_intro.typ
++++ b/init-files/sections/01_intro.typ
+@@ -1,2 +1,2 @@
+-#import "../../paddling-tongji-thesis/tongjithesis.typ": *
++#import "@preview/paddling-tongji-thesis:0.1.1": *
+
+diff --git a/init-files/sections/02_math.typ b/init-files/sections/02_math.typ
+index 53aba17..d90ba0a 100644
+--- a/init-files/sections/02_math.typ
++++ b/init-files/sections/02_math.typ
+@@ -1,2 +1,2 @@
+-#import "../../paddling-tongji-thesis/tongjithesis.typ": *
++#import "@preview/paddling-tongji-thesis:0.1.1": *
+
+diff --git a/init-files/sections/03_reference.typ b/init-files/sections/03_reference.typ
+index 9388431..4d8bf7a 100644
+--- a/init-files/sections/03_reference.typ
++++ b/init-files/sections/03_reference.typ
+@@ -1,2 +1,2 @@
+-#import "../../paddling-tongji-thesis/tongjithesis.typ": *
++#import "@preview/paddling-tongji-thesis:0.1.1": *
+
+diff --git a/init-files/sections/04_figure.typ b/init-files/sections/04_figure.typ
+index ae430cb..6db57e2 100644
+--- a/init-files/sections/04_figure.typ
++++ b/init-files/sections/04_figure.typ
+@@ -1,2 +1,2 @@
+-#import "../../paddling-tongji-thesis/tongjithesis.typ": *
++#import "@preview/paddling-tongji-thesis:0.1.1": *
+
+diff --git a/init-files/sections/05_conclusion.typ b/init-files/sections/05_conclusion.typ
+index 13f77d3..bbf6b54 100644
+--- a/init-files/sections/05_conclusion.typ
++++ b/init-files/sections/05_conclusion.typ
+@@ -1,2 +1,2 @@
+-#import "../../paddling-tongji-thesis/tongjithesis.typ": *
++#import "@preview/paddling-tongji-thesis:0.1.1": *
+
+diff --git a/init-files/sections/acknowledgments.typ b/init-files/sections/acknowledgments.typ
+index 58a6d24..13dce10 100644
+--- a/init-files/sections/acknowledgments.typ
++++ b/init-files/sections/acknowledgments.typ
+@@ -1,2 +1,2 @@
+-#import "../../paddling-tongji-thesis/tongjithesis.typ": *
++#import "@preview/paddling-tongji-thesis:0.1.1": *
+
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,24 @@
+### :warning: 提交 PR 需要注意的事项
+
+<!--在提交 PR 前，还请检查下列选项是否已经完成-->
+
+- [ ] 已通读 [CONTRIBUTING](../CONTRIBUTING.md) 文档中对 Pull request 的流程规定。
+- [ ] 如果提供的是 “模板功能特性” 相关的代码，已经写好了较为易懂的注释，并修改了对应的文档。
+- [ ] 如果提供的是 “模板功能特性” 相关的代码，已尽可能在各平台上进行了测试。
+- [ ] 确定该部分（:warning: 提交 PR 需要注意的事项）已在正式 PR 中被删去。
+
+## 对该 PR 的总结
+
+<!--感谢同学的贡献，还希望在此处通过 “无序列表” 的方式列出该 PR 所做的工作-->
+
+### 该 PR 的成功合入是否需要关闭一些 Issue？
+
+<!--还请使用 “Close #id” 的方式给出-->
+
+### 该 PR 的功能展示
+
+<!--如果该 PR 与 “模板功能特性” 相关且较为方便的话，那么还请给出 PR 合入后对编译产物的影响。例如，可以上传一些图片-->
+
+### 该 PR 的其他信息
+
+<!--这里用于提出其他与该 PR 相关的信息-->
diff --git a/.github/workflows/prepare_release.yml b/.github/workflows/prepare_release.yml
@@ -0,0 +1,23 @@
+name: Prepare Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  apply-patch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Git
+        run: |
+          git config --global user.name 'github-actions'
+          git config --global user.email '[email protected]'
+
+      - name: Apply patch and create new branch
+        run: |
+          chmod +x .github/bin/package_release.sh
+          .github/bin/package_release.sh
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,9 +2,9 @@
 
 ## Contents
 
-* source files: as a template repository, "source files" are ".typ", ".bib" and some related files with other extension names.
-* doc files: including all ".typ" files and even "main.typ", which show how to use "source files".
-* config files: These files make our development and use of templates more standardlized (e.g. .gitignore).
+- source files: as a template repository, "source files" are ".typ", ".bib" and some related files with other extension names.
+- doc files: including all ".typ" files and even "main.typ", which show how to use "source files".
+- config files: These files make our development and use of templates more standardlized (e.g. .gitignore).
 
 ## How to contribute
 
@@ -27,4 +27,18 @@ We recommend to follow this workflow step by step:
 3. Create a new local branch as a work branch.
 4. Commit some changes on the work branch.
 5. Push the new local branch to remote with commits.
-6. Pull request, from the new remote branch to any branch of upstream repository.
+6. Pull request, from the new remote branch to any branch of upstream repository.
+
+### Before your pull request
+
+Remember to check whether you have added, renamed or removed file in `init-files/`. If so, please update the `.github/patches/package_release.diff` and commit it along with your pull request.
+
+如果你新增、移动或删除了`init-files/`目录下的文件，请检查是否需要更新`.github/patches/package_release.diff`，并将其随PR一同提出。
+
+> [!TIP]
+> You can use `git diff HEAD~1 HEAD > package_release.diff` to generate a patch that can be accepted.
+
+> [!IMPORTANT]
+> We use `git apply` to apply the patch and generate a package-release branch. Please check if your patch can be applied successfully. If not, we may not be able to merge your branch.
+>
+> 请务必确保patch可以被`git apply`命令应用。如果patch未更新或无法被正确应用，我们可能将无法合并您的分支。
diff --git a/README-EN.md b/README-EN.md
@@ -1,4 +1,3 @@
-
 # :page_facing_up: Tongji University Undergraduate Thesis Typst Template (STEM)
 
 [中文](README.md) | English
@@ -21,68 +20,65 @@ Below are displayed in order the "Cover", "Chinese Abstract", "Table of Contents
       <img src="https://media.githubusercontent.com/media/TJ-CSCCG/TJCS-Images/tongji-undergrad-thesis-typst/preview/main_page-0020.jpg" width="30%">
 </p>
 
-## How to Use
+## Usage Instructions
 
 ### Online Web App
 
-Please open [https://typst.app/universe/package/tongji-undergrad-thesis](https://typst.app/universe/package/tongji-undergrad-thesis) and click `Create project in app` , or choose `Start from a template`in the Web App, and choose `tongji-undergrad-thesis`.
+#### Create Project
 
-And then, please upload **all** fonts from [https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst/tree/fonts/fonts](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst/tree/fonts/fonts) to the root directory of the project in the Web App.
+- Open [![svg of typst-tongjithesis](https://img.shields.io/badge/Typst-paddling--tongji--thesis-239dae)](https://www.overleaf.com/latex/templates/tongji-university-undergraduate-thesis-template/tfvdvyggqybn) and click `Create project in app`.
 
-### Local - With typst init
+- Or select `Start from a template` in the [Typst Web App](https://typst.app), then choose `paddling-tongji-thesis`.
 
-#### 1. Install Typst
+#### Upload Fonts
 
-Refer to the [Typst](https://github.com/typst/typst?tab=readme-ov-file#installation) official documentation for installation.
+Download all font files from the [`fonts` branch](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst/tree/fonts) and upload them to the root directory of the project in the Typst Web App. You can then start using the template.
 
-#### 2. Init the project from the template
+### Local Usage
 
-```bash
-typst init @preview/tongji-undergrad-thesis
-```
+#### 1. Install Typst
 
-#### 3. Download Fonts
+Follow the [Typst official documentation](https://github.com/typst/typst?tab=readme-ov-file#installation) to install Typst.
 
-Please download the font files from the [`fonts`](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst/tree/fonts) branch of this repository and install the font files to your system.
+#### 2. Download Fonts
 
-#### 4. Compile
+Download all font files from the [`fonts` branch](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst/tree/fonts) and **install them on your system**.
 
-Modify related files as needed, then execute the following command to compile.
+#### Initialization using `typst`
+
+##### Initialize Project
 
 ```bash
-typst compile main.typ
+typst init @preview/paddling-tongji-thesis
 ```
 
-> [!TIP]
-> If you find that the fonts are not displayed properly, please install the fonts to your system and then execute the compile command.
+##### Compile
 
-### Local - With git clone
-
-#### 1. Install Typst
+```bash
+typst compile main.typ
+```
 
-Refer to the [Typst](https://github.com/typst/typst?tab=readme-ov-file#installation) official documentation for installation.
+#### Initialization using `git clone`
 
-#### 2. Clone this project
+##### Git Clone Project
 
 ```bash
 git clone https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst.git
 cd tongji-undergrad-thesis-typst
 ```
 
-#### 3. Download Fonts
-
-Please download the font files from the [`fonts`](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst/tree/fonts) branch of this repository and place them in the `fonts` folder, or install the font files to your system.
-
-#### 4. Compile
-
-Modify related files in `init-files` as needed, then execute the following command to compile.
+##### Compile
 
 ```bash
-typst --font-path ./fonts compile init-files/main.typ --root .
+typst compile init-files/main.typ --root .
 ```
 
 > [!TIP]
-> If you find that the fonts are not displayed properly, please install the font files in the `fonts` folder to your system and then execute the compile command.
+> If you don't want to install the fonts used by the project on your system, you can specify the font path during compilation, for example:
+>
+> ```bash
+> typst compile init-files/main.typ --root . --font-path {YOUR_FONT_PATH}
+> ```
 
 ## How to Contribute to This Project?
 
@@ -98,8 +94,8 @@ This project uses fonts from the FounderType font library, with copyright belong
 
 ## Acknowledgments for Outstanding Contributions
 
-* This project originated from [FeO3](https://github.com/seashell11234455)'s initial version project [tongji-undergrad-thesis-typst](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst/tree/lky).
-* Later, [RizhongLin](https://github.com/RizhongLin) improved the template to better meet the requirements of Tongji University undergraduate thesis, and added basic tutorials for Typst.
+- This project originated from [FeO3](https://github.com/seashell11234455)'s initial version project [tongji-undergrad-thesis-typst](https://github.com/TJ-CSCCG/tongji-undergrad-thesis-typst/tree/lky).
+- Later, [RizhongLin](https://github.com/RizhongLin) improved the template to better meet the requirements of Tongji University undergraduate thesis, and added basic tutorials for Typst.
 
 We are very grateful to the above contributors for their efforts, which have provided convenience and help to more students.
 
@@ -109,8 +105,8 @@ When using this template, if you find this project helpful for your graduation p
 
 We have learned a lot from the excellent open-source projects of top universities:
 
-* [lucifer1004/pkuthss-typst](https://github.com/lucifer1004/pkuthss-typst)
-* [werifu/HUST-typst-template](https://github.com/werifu/HUST-typst-template)
+- [lucifer1004/pkuthss-typst](https://github.com/lucifer1004/pkuthss-typst)
+- [werifu/HUST-typst-template](https://github.com/werifu/HUST-typst-template)
 
 ## Contact
 
@@ -119,4 +115,7 @@ We have learned a lot from the excellent open-source projects of top universitie
 [
     'rizhonglin@$.%'.replace('$', 'epfl').replace('%', 'ch'),
 ]
-```
+```
+### QQ Group
+
+- TJ-CSCCG Communication Group: `1013806782`