Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

contrib: add community contrib feature #79

Merged
merged 42 commits into from
Jan 30, 2022
Merged

Conversation

LogCreative
Copy link
Contributor

@LogCreative LogCreative commented Dec 1, 2021

建设社区

处于草案阶段。所有的细节还有待讨论。

希望添加一个 good first issue 来提高社区建设:开发者可以向根目录下的 contrib 目录添加自定义的模板(子主题)。并添加内置指令

  • \getcontribdir{#1} 获得 #1 主题的文件夹目录
  • \getcontribpath{#1}{#2} 获得 #1 主题的文件夹 #2 文件路径
  • \usemytheme{#1} 使用 #1 子主题,在加载 sjtubeamer 主要主题后使用
  • \definelogo 添加一个可选参数用于接受文件夹路径

这样就可以固化一些社区贡献模板,每一个文件夹就是一个小工作区,可以添加一些自定义图片,环境有了隔离。并且并没有离开 sjtubeamer 的开发环境,可以

  • 使用 sjtucoversjtuvi 的所有工具
  • 根据主要主题的参数进行可适应性配置\EqualOption{}{}{}可以判断其他文件的参数情况,由于 \usemytheme 在主要主题入口文件定义,不能在仅加载 innerouter 主题时使用my主题,也就意味着整个主模板在完整加载的状态。
  • 或者魔改主要主题的一些宏(因为是覆盖加载)
  • 好的模板可以被选择移入 sjtucover

但是加载 .ltx 文件并不能接受参数,希望添加其他参数应该向内核提供 PR。(或者等我想到了更好地传递参数方法,我觉得可以不允许添加额外的子模板参数,这样可以保证整体的统一性)参数可以通过内部接口传递。

而 Release 时不会放入这些contrib文件夹,直接下载 Code 会下载这些社区贡献子主题。(这样就更应该下载 Release 了)

  • 稳定接口
  • 添加 CONTRIBUTING.md
  • 添加 good first issue 贡献插件😎 #81
  • 设置action-bot用于对contrib标签的模板生成预览
  • 考虑使用子模块贡献的可能性 如果这个插件希望活跃更新 可以直接在contrib里添加子模块而不固化 特别是插件比较大的时候 就可以通过这种方式节约空间
  • SJTUVI 包独立草案 #77 不应当更改表面接口

@LogCreative LogCreative marked this pull request as draft December 1, 2021 14:46
@LogCreative
Copy link
Contributor Author

等待上游分支合并后再结束 draft 状态。

@LogCreative LogCreative added this to the v3 milestone Dec 1, 2021
@LogCreative LogCreative added the contrib Contribute a sub theme label Dec 1, 2021
@LogCreative
Copy link
Contributor Author

贡献的 PR 可以添加 contrib 标签来表示想要提交一个子主题(插件)。

@LogCreative LogCreative changed the base branch from logcreative-coverpage to main December 2, 2021 08:11
@LogCreative LogCreative marked this pull request as ready for review December 2, 2021 08:12
@LogCreative LogCreative marked this pull request as draft December 2, 2021 08:12
@LogCreative LogCreative changed the base branch from main to logcreative-coverpage December 2, 2021 08:14
@LogCreative LogCreative changed the base branch from logcreative-coverpage to main December 3, 2021 02:08
@LogCreative LogCreative marked this pull request as ready for review December 3, 2021 02:08
@LogCreative LogCreative marked this pull request as draft December 3, 2021 02:29
@LogCreative LogCreative changed the base branch from main to logcreative-coverpage December 3, 2021 06:25
@LogCreative
Copy link
Contributor Author

LogCreative commented Dec 3, 2021

插件化工作还在进行中。下面是一些暂时思考到的一些想法。

贡献子主题/插件的意义:

  • 或许很多人可以提供ta的第一个PR
  • 为一些重度使用TeX的机构提供定制化的beamer主题(含有特有logo,需要遵循一定的协议)
  • 为一些主题的beamer提供一个大纲示例文档

插件化工作的意义:

  • TeX 虽然作为编码类排版门槛高,但是我认为这也恰恰获得了比 PowerPoint 更好的扩展性,可以比较一下,如果我想要搞一个PowerPoint扩展,光开工程已经劝退了很多人,更不要说怎么去搞个性化模块了(翻阅大量文档学习C#和API)。
  • TeX 写自己的主题配置/插件就相对轻松一些,并没有离开自己熟悉的编程环境,语法仍然可以应用,宏包也是统一管理的。
  • 通过插件化,用户可以选择加载某些部分,这比全部放在内核里效率要高。
  • 简化修改模板的方法,简单一些行就可以完成改动,不需要过多地关注src里的中层内容。
  • 好的插件工作可以被移入内核中,更为广泛地使用。
  • 使用镜像更新,只需要git pull一下,如果用户是在根目录创建了一个新的tex文件编写文档,就不用担心冲突的问题。
  • 搞了自己的一套 TeX Distribution,距离 Chi TeX 不远了(逃

@LogCreative
Copy link
Contributor Author

LogCreative commented Dec 3, 2021

目前的添加插件的流程:

  • fork 仓库(从镜像站克隆的是无法提交PR的)
  • 在 contrib 里新建文件夹 project,包含
    • sjtubeamerproject.ltx 样式文件(直接通过 \usemytheme[]{project} 调用)
    • project.tex 样例文件(如果是一份大纲,用户可以直接copy到根目录对应的文件中)
    • 其他的依赖文件(图标之类)
  • 进入 src 文件夹执行 l3build install 安装到自己的环境中。(这个问题终于在 11/30 的更新修复了)
  • 边更改样式文件,可以边编写样例文档 debug。(由于采用智能判断是否是debug模式,会自动更改路径)
  • 完成后 contribute 到这个仓库,发PR。
  • action-bot 会根据样例文档编译并生成编译结果并作为评论。(还没写,这种带contrib的action应该简单一些,直接只需要编译样例文档就行,内核会完整构建包,发布还会编译更多的样例)
  • review 这个PR,通过。
  • action-bot在源文件开头写下作者信息之类的东西,或者是在 good first issue 里评论这个插件的内容
  • 合并主线,action-bot会提示可以在 Discussion 发个帖子,其余的人询问这个子主题相关的问题可以去这个帖子提问。(我觉得到这个时候discussion就可以开了,区别于issue是用来排除bug的,初期可能需要一段时间的原始积累)
  • 之后还有更新可以再发 PR,但是不推荐对一个包进行频繁更新,如果希望频繁更新,可以作为子模块嵌入。

@LogCreative
Copy link
Contributor Author

LogCreative commented Dec 3, 2021

目前考虑到的要review什么:

  • 是否与之前的模块有重复,如果有,可以建议合并一下。
  • 是否需要遵循一定的协议,是否用了版权图
  • 观察结果,并按主观意愿决定是否合并

@LogCreative
Copy link
Contributor Author

LogCreative commented Dec 3, 2021

目前能够考虑到的类型:

  • 子主题 通过20行左右的修改得到一个简单的配置文件,或者更多行的定义得到更加个性化的效果
  • 插件 可以通过预定义一些命令得到一些简单的区块,甚至是一些tikz图模板
  • 主题大纲 提供一个基本结构的书写方法
  • 子模块 直接是一个长期更新的项目,挂到这个上面。

@LogCreative
Copy link
Contributor Author

内核还要做什么:

  • 稳定API不要对老的有太大变动,否则会导致插件崩溃
  • 增加更多的共性功能。
  • 加快编译速度(这是一个艰难的话题)
  • 语言上的优化(更方便地写代码)

@LogCreative LogCreative marked this pull request as ready for review December 10, 2021 03:42
@LogCreative LogCreative marked this pull request as draft December 10, 2021 03:42
Base automatically changed from logcreative-coverpage to main December 12, 2021 05:00
@LogCreative LogCreative temporarily deployed to IMGUR December 31, 2021 02:16 Inactive
@github-actions

This comment has been minimized.

@LogCreative
Copy link
Contributor Author

我觉得创建一个 good first issue 后 改一下yaml 可以合并了

@skyzh
Copy link
Member

skyzh commented Jan 4, 2022

我觉得创建一个 good first issue 后 改一下yaml 可以合并了

成功!晚点一定(

@LogCreative
Copy link
Contributor Author

yaml 多看看 我不知道对不对(push还没试
😎 或许开issue和审核插件 @cascades-sjtu 有没有兴趣

@x14ngch3n
Copy link
Member

👍 不好意思啊,我前段时间在准备考试,我考完试来看看

Copy link
Member

@skyzh skyzh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rest LGTM, good work!

)
}}
- uses: jungwinter/comment@v1
if: github.event_name == 'push'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we really need to comment on pushes? I would prefer only doing comments on pull-requests.

Copy link
Contributor Author

@LogCreative LogCreative Jan 16, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention here is to make a collection of templates in an issue so that the user could select the theme in an easier way. Since the doc of the plug-in will not be included in the repo. It is a workaround for that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And it has not been tested.

id: contrib_png
with:
path: ./build/contrib.*.png
client_id: ${{secrets.IMGUR_CLIENT_ID}}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everyone who creates PR can now access this secret. Is it expected?

Copy link
Contributor Author

@LogCreative LogCreative Jan 16, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems that if someone pulls a request, then collaborator approves it, the secret could be accessed. (idk)

@LogCreative
Copy link
Contributor Author

如果 @cascades-sjtu 感兴趣的话,可以发个 issue 用于整合,然后修改 yaml 里的 issue 号,这个分支就可以合并了

@LogCreative LogCreative temporarily deployed to IMGUR January 17, 2022 07:56 Inactive
@github-actions
Copy link

Thank you for contributing to SJTUBeamer!

Here is the preview of your contribution documentation.

Imgur Images

@LogCreative
Copy link
Contributor Author

那我发 issue 准备合并了(

@skyzh
Copy link
Member

skyzh commented Jan 30, 2022

滋瓷!

@LogCreative LogCreative merged commit d2ae3df into main Jan 30, 2022
@LogCreative LogCreative deleted the logcreative-contrib branch January 30, 2022 13:35
@LogCreative
Copy link
Contributor Author

ci 我再修修 试试一些功能后 争取过年后 release(

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
contrib Contribute a sub theme
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants