以下のエントリで触れてますが、GitHubにOSSを公開したときの手順を備忘録として記録します。
手順
GitHubに公開用のリポジトリを作成し、コードをPushする
Pushするまでは割愛します。
一つハマったことはコード書いてる途中に気づいたんですけど、手元の Go のバージョンが Go1.12 以上の場合、go.mod の設定で go1.12 が付いてきてしまって、Go1.11 でビルドしてるプロジェクトで go get ができなくなりました。go.mod ファイルから go1.12 を消しておくか、今のところは go1.11 で go mod init しておくといいかなと思います。
追記: 僕の手元の環境がおかしいだけだったっぽいです。
LICENCE を設定する
ライセンスを登録します。
ライセンスについては全く意識したことなかったのですが、同僚が OSS 公開したら海外の別のエンジニアにコード丸パクリされたというのを見ていたので、ちゃんと設定しないといけないな！と思って設定方法調べました。
どのライセンスが〜みたいな詳細はここでは触れませんが、今回は MIT を選択しておきました。
GitHub の対象リポジトリから「create new file」 を選択して「license」と入力すると license のテンプレートが出てくるのでライセンスにするか選んで commit します。
ちなみに後から知ったんですが、リポジトリ作成時にライセンス選択できるっぽいです。知りませんでした。
CI を設定する
今回は travis.ci を使いました。
使い方は結構簡単で、travis.ci に GitHub を連携させて CI を追加したいリポジトリを選択するだけです。
リポジトリを選択するだけだと CI は回らないので、https://docs.travis-ci.com/user/languages/go を参考に設定ファイルを作ってリポジトリに commit します。
自分は初めてだったので簡単な設定にしました。
ref: https://github.com/emahiro/ae-plain-logger/blob/master/.travis.yml
今回は設定が簡単だったので travis を採用しましたが、ちょうど GitHub Actions で CI/CD がサポートされたタイミングだったのでこっちを使ってもよかったかもしれないなーと思いました。
Go Report Card を登録する
プロジェクト内のコードの品質をオンラインで検査してくれる https://goreportcard.com にリポジトリを登録します。
上記のURLにアクセスし、検査したいリポジトリの GitHub の URL を入力します。
以下のようにプロジェクト内のコードをオンラインで検査してくれます。
Godocを書く
今回はあまりちゃんとは書いてないですが、公開メソッドや sturct に対してコメントを追加する、という最低限の Godoc の記法に則ったものだけは記載しました。
Google のコードとか読んでるよすごい量のコードコメントが書いてあって圧倒されますが、今回はそこまでしなくていいかなーくらいのノリでした。少しずつちゃんと書いていきたいなと思ってます。
流石に適当な英語が多すぎ、かつ pacic する可能性があるのにそのことが実装を読まないとわからないのは不親切すぎたので以下の PR で Godoc を拡充しました。
何をどう書いたらいいかわからなかったのですでにある godoc を参考にして記載しました。
- panic にするケースにおけるコメント => https://golang.org/pkg/net/http/#ServeMux.Handle
- net/http のパッケージでは Handle が panic するときに panic を動詞で使っていたので参考にしました。
- format するケースにおけるコメント => https://github.com/golang/appengine/tree/master/log/api.go#L18
- log は appengine/log のコメントをほぼ丸々参照しました。
現在の godoc はこのようになっています。
追加で package document を書きました。
以下のようにパッケージ宣言の上にコメントを記載するとパッケージの説明を godoc が拾ってくれます。
/* Package log is ~ Example: ctx := request.Context() // タブで一段下がるとコードレイアウトとして描画してくれます。 */ package log
画像で示すと以下の部分が package document が反映された部分になります。
ここまで書いて最後に godoc の batch を README.md に追加しました。 ?status.svc をつけて挿入します。
[](https://godoc.org/github.com/emahiro/ae-plain-logger)
まとめ
外に出して恥ずかしくないコードを書く、というのは色んな手順を踏む必要がありました。
特に Godoc は普段仕事のコードを書く時にはとりあえず lint を防ぐ目的でしか使ってなかったりするので、ドキュメントを使う人のために書く、というのは慣れずにフィードバックをもらいながら調整していきました。
書きたい文章を Google 翻訳にかけてもイマイチピンとこない英訳だったので、これを機会に普段馴染みのある package の Godoc をひたすら漁ったりしてました。結構いい方法だと思いました。
Godoc を書かないと、Godocの正しい書き方がわからない、ということを学びました。
今回初めて色々やってみたので、次からは迷わずにやっていけそうです。
追記: internal package 化
以下のPRで spancontext package を internal に移動しました。理由は外から触れたくないからです。この辺も internal package は外から触れないことは知ってましたが、意図して internal に囲い込むという手法もライブラリを作ることで学べたことでした。
追記2: タグの切り方
リリースタグを切るときに vX.X.X のように vをつけないと go.mod でコミットハッシュのバージョン管理をされてしまいます。
vなしでタグを切ったとき
// go.mod github.com/emahiro/ae-plain-logger v0.0.0-20190815145805-39cea2e23c34
vつきでタグを切ったとき
// go.mod github.com/emahiro/ae-plain-logger v0.2.0
