Go package 发布

Table of Contents

1. 发布到 pkg.go.dev 1

pkg.go.dev 的数据是从 proxy.golang.org 下载的,定期监控 Go Module Index 然后添加到 pkg.go.dev。 如果没有更新,以 github.com/zhangjie2012/yo-kit 为例,以下三种方法均可,第一种更快:

  1. 打开 https://pkg.go.dev/github.com/zhangjie2012/yo-kit 然后点击 Request "github.com/zhangjie2012/yo-kit" 按钮
  2. 向 proxy.golang.org 发出模块版本请求,比如 https://proxy.golang.org/github.com/zhangjie2012/yo-kit/@v/main.info
  3. 通过命令行下载该 package GOPROXY=https://proxy.golang.org GO111MODULE=on go get github.com/zhangjie2012/yo-kit@main

然后就可以在 https://pkg.go.dev/github.com/zhangjie2012/yo-kit 中看到文档了。

proxy.golang.org 的说明

Go 模块的全局镜像。当然国内有七牛的 https://goproxy.cn/ 官方的 https://goproxy.io/zh/ 可用,是不是直接把 proxy.golang.org 作为上游镜像,我不太确定。

为什么提交了新的改动,但是 go get -u 或者 go list -m --version 中没有出现呢?

  1. 有缓存,正常情况 30 分钟左右后生效
  2. 如果想要快速生效(1分钟左右),需要做一个版本发布(新建一个语义化的版本号,然后在 get 后面指定)
  3. 如果不想使用 GOPROXY,package 本身是公开的,则可以通过设置 GOPROXY=direct 来跳过 PROXY,直接从 repo 拉取

2. 从 go.dev 移除

  1. 在 go.mod 中添加 retract 指令,查看 https://go.dev/blog/go116-module-changes 文档中的 Module retraction 小节
  2. 向 Go 开发团队提出 request

两种方式其实都挺麻烦的。

3. 文档

pkg.go.dev 是根据代码中的文档(注释)自动生成的(godoc 工具自动提取),书写规范:Go Doc Comments

4. 最佳实践

  • 拥有一个 go.mod 文件 Go 1.11 后引入了官方的模块管理工具 go mod
  • 可分发 LICENSE 使用少三方使用限制的开源协议,你的项目中根目录下需要有一个 LICENSE 文件
  • Tagged 版本 解析 package 时,优先使用 tag 标记的版本,如果没有 tag,则会寻找最新的提交记录(可读性差)
  • Stable 版本 v0 是实验性版本,v1 或已上会被认为是个稳定版本,破坏性的更新会在大版本中;稳定版本之后的次要版本 通常认为是兼容的。

LICENSE 如何选择?

  1. https://docs.github.com/cn/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository
  2. https://www.ruanyifeng.com/blog/2011/05/how_to_choose_free_software_licenses.html

我一般选择 MIT 或者 Apache。

对于版本管理?

我的理解是,如果是自己使用没太必要用 tag 来维护,比较麻烦,全部推 main 分支即可。但如果考虑开源或者存在不兼容的情况, 是需要严格的版本管理机制的。

5. 自动构建

Github Actions 中添加一个 workflow,其实是个 git hook,在每次提交的时候会触发自动构建。

构建成功的会有一个徽标,你可以放到 README.md 中,看起来酷酷的。

6. go.dev 的徽标

以前 https://github.com/golang/go/issues/36982 不支持,用第三方的 https://shields.io 来替代。目前已经支持了:https://pkg.go.dev/badge/

Footnotes:

First created: 2020-07-22 10:51:56
Last updated: 2022-12-11 Sun 12:49
Power by Emacs 29.0.91 (Org mode 9.6.6)