開発再開メモ

[akabekobeko]

VFM 開発を担当することになったので、現状の GitHub と Node.js プロジェクト構成などを調査してゆく。その過程で今後どのように開発を進めるかなのを検討、考察を本 issue へメモ書きしてゆく。

[akabekobeko]

Projects について。現在は v1 と Spec がある。v1 は Milestone 的に v1.0.0 リリースに含めたい機能の進捗管理に利用されており、Spec はより長期的な展望の仕様策定となっている。

v1 は v1.0.0 リリースまで、Spec は永続的に利用する。v1.0.0 以降は Milestone でよいかもしれない。

[akabekobeko]

Node.js (npm) プロジェクト構成について。よくある構造であるが、私にとって馴染みないものもあるため個別に役割などをメモしてゆく。まずは tree -L 1 -F して構成を出力。

.
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── assets/
├── docs/
├── jest.config.js
├── lerna.json
├── node_modules/
├── package-lock.json
├── package.json
├── src/
├── tests/
├── tsconfig.json
├── types/
└── yarn.lock

それぞれについてメモ。.* を出力し忘れたので追加している。

File/Directory	Comment
.github/	GitHub プロジェクト設定用ディレクトリー。既に CI 設定などもなされているため踏襲でよいだろう。
assets/	ドキュメントから参照される静的リリース置き場。現在は README のヘッダー画像を格納している。
docs/	資料。VFM の Web サイトを構築するための素材らしきものが格納されている。CONTRIBUTING.md には特に解説なし。
node_modules/	npm ディレクトリー。
src/	開発用コード格納ディレクトリー。
tests/	Jest によるテスト コード格納ディレクトリー。
types/	TypeScript 型設定を格納するディレクトリー。*.d.ts を提供しない npm の型解決などに使用されているため "declaration": true にしたとしても要る。たぶん hast や mdast 系は今後も *.d.ts を提供しなさそうだし。
.eslintrc	ESLint 設定。
.prettierrc	Prettier 設定。現在のルールは 3 種類。Vivliostyle Project としては Prettier 標準という話があった気がする。このままでゆくか他のメンバーと相談が必要。
CHANGELOG.md	更新履歴。自動生成される。
CONTRIBUTING.md	開発に参加するためのメモ。リリース手順などが記載されている。
LICENSE	ライセンス。Apache License, Version 2.0 を採用。README.md の badge が unknown になっているが、設定不足？
README.md	README。開発者は yarn、これが対象とするエンド ユーザーは npm で環境構築する方針のようだ。
jest.config.js	ユニット テスト ツール、Jest 設定。
lerna.json	monorepo 用の設定。標準の packages/* を設定しているが実体なし。将来 src/plugins の構文を個別に npm 配信する計画のために用意されたものと思われる。
package-lock.json	npm の構成ロック用ファイル。私のローカルで生成したもの。yarn を利用せず npm でゆくなら必要。どうするか迷っている。
package.json	Node.js (npm) プロジェクト構成ファイル。
tsconfig.json	TypeScript 設定ファイル。
yarn.lock	yarn の構成ロック用ファイル。最近の npm はこちらにも対応していて npm i すると更新してくれる。よって package-lock.json を gitignore すれば npm でも開発してゆけそう。

[akabekobeko]

基本は CONTRIBUTING.md を参考に現在の構成と設計を維持しながら、v1 対応予定の機能をいくつか実装してみて理解を深めてみる。ざっと見る限りさすが uetchy さんという感じでモダーンな構成だ。

[akabekobeko]

私はなるべく標準を重視するため yarn ではなく npm 派なのだが CONTRIBUTING.md にも明示されているので、当面は yarn でゆく。よって package-lock.json は生成せずコミットもしない。

[akabekobeko]

Vivliostyle としての GitHub/Git リポジトリー開発運用を知りたかったので Slack に質問を投稿。

@shinyu @spring-raining
質問です。Vivliostyle 関連の開発をする際、Git リポジトリーのブランチや Pull Request はどのように管理していますか？

1. git clone したリポジトリーの master へ直に commit/push
2. git clone したリポジトリーにローカルで作業ブランチを追加して Pull Request 作成 & merge
3. fork したリポジトリーの master へ直に commit/push して GitHub 上で本家に対して Pull Request 作成
4. fork したリポジトリーに作業ブランチを追加して commit/push 後、GitHub やなんらかのクライアント (CLI や SourceTree) で Pull Request 作成
5. その他

すると @spring-raining さんから以下の回答を得られた。

vivliostyle repoへのpush権限がある場合は2. ない場合は4. です。akabekoさんの場合は2.も可能かと思います

本リポジトリーについて Admine 権限 (当然 Write 権もあり) をいただいたので 2 でゆく。

[akabekobeko]

GitHub リポジトリーについて、この問題は解決していない。

そういえば Admin 権限があるのに GitHub 上だと vfm リポジトリーに Settings が表示されないですね。もしかして uetchy さんと私の二人が Admin だと先に登録された uetchy さんが owner になって表示されないとか？

なお Settings ページそのものは URL 直でアクセス可能です。

[akabekobeko]

本リポジトリーの merge 設定を確認したら Automatically delete head branches がチェックされていた。標準では無効なので明示的にチェックしたのだろう。よってはるさめさんの提案どおり作業ブランチを作成して Pull Request するのがよいだろう。

Pull Request のレビュー担当はとりあえず私としておく。既に過去のセキュリティー警告 PR をそうしたので。

[akabekobeko]

実装を把握するためにユニットテストを読んでいる。

Jest の it に指定している buildProcessorTestingCode により定型化。この高階関数は Markdown の解析結果となる MDAST と変換された HTML の期待値を指定することで成否をテストしてくれる。大半のテストはこの定型に収まるだろうから便利だ。継続利用する予定。

[akabekobeko]

src/ を読む。以前 akabekobeko/env-create-book を実装した際に利用した npm が散見される。

unified まわりを学べば理解できそうだ。VFM として新規追加する Markdown 構文は基本的に正規表現で解析して AST を返せばよいらしい。

[akabekobeko]

いつの間にか Settings が表示されるようになっていた。表示されなかった時にキャッシュを消してのリロードも試してダメだったのだが、なにか変化でもあったろうか？

[akabekobeko]

#41 が修正済みとのことなので反映するためリリースを試みたが失敗する。

$ yarn release:pre
yarn run v1.22.10
$ release-it --preRelease --npm.tag=next
ERROR Not authenticated with npm. Please `npm login` and try again.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

メッセージどおり npm login を実行。

$ npm login
npm notice Log in on https://registry.npmjs.org/
Username: akabeko
Password:
Email: (this IS public) akabekobeko@gmail.com
Logged in as akabeko on https://registry.npmjs.org/.

再試行しても同じエラーになる。村上さんによれば @vivliostyle に対して権限はあるとのこと。設定ページ https://www.npmjs.com/package/@vivliostyle/vfm/access も見られる。

[akabekobeko]

CONTRIBUTING.md にしたがい yarn で実行しているが、これにも login コマンドがあるので実行。

$ yarn login 
yarn login v1.22.10
question npm username: akabeko
question npm email: akabekobeko@gmail.com
✨  Done in 27.76s.

しかし yarn release:pre を再試行したら同様のエラーが。CLI としての npm と yarn 設定ではないのかもしれない。

[akabekobeko]

npm run で試したらエラー メッセージに原因らしき情報があった。

$ npm run release:pre

> @vivliostyle/vfm@1.0.0-alpha.10 release:pre
> release-it --preRelease --npm.tag=next

ERROR Environment variable "GITHUB_TOKEN" is required for GitHub releases.
Documentation: https://github.com/release-it/release-it#github-releases

GitHub 関連の環境設定が必要らしい。

[akabekobeko]

GITHUB_TOKEN が必要とのことなので https://github.com/release-it/release-it#github-releases を読みながら設定してみた。

1. Configure github.release: true これは VFM リポジトリー内の .release-it.json に設定済み
2. Obtain a personal access token... 自分のアカウントに対して生成するものなのでリンク先で生成
3. Make sure the token is... 私の環境は macOS でシェルは zsh なので ~/.zshrc に指定

この状態で source .zshrc してから export -p で GITHUB_TOKEN が定義されていることを確認。yarn release:pre は前述と同じエラーだった。そこで GITHUB_TOKEN など詳細な情報を得られる npm run release:pre を実行。

$ npm run release:pre

> @vivliostyle/vfm@1.0.0-alpha.10 release:pre
> release-it --preRelease --npm.tag=next

ERROR Working dir must be clean.
Please stage and commit your changes.
Alternatively, use `--no-git.requireCleanWorkingDir` to include the changes in the release commit (or save `"git.requireCleanWorkingDir": false` in the configuration).

コマンド以外に Git 操作が必要なのだろうか？継続調査する。

[akabekobeko]

Please stage and commit your changes. のほうが原因らしい。remote に更新 (dependabot の PR と私の Issue Template 更新) があったので pull してみた。その後に yarn release:pre を実行したら従来と同じエラーだったので npm run release:pre を実行したら対話形式でリリースが開始された。

$ npm run release:pre

> @vivliostyle/vfm@1.0.0-alpha.10 release:pre
> release-it --preRelease --npm.tag=next


🚀 Let's release @vivliostyle/vfm (currently at 1.0.0-alpha.10)


Changelog:
# [1.0.0-alpha.11](https://github.com/vivliostyle/vfm/compare/v1.0.0-alpha.10...v1.0.0-alpha.11) (2020-12-16)

### Bug Fixes
* handle multiline input ([f1afb20](https://github.com/vivliostyle/vfm/commit/f1afb206d18d15f5f9c6d49b14a69fbc0eaa08c0))

### Features
* Add code block tests ([687227b](https://github.com/vivliostyle/vfm/commit/687227b7a3d43df5c07ae2008db381e9c0aed33f))
* Add math block tests ([b03bb73](https://github.com/vivliostyle/vfm/commit/b03bb7304f7dfba95e4fe0b94f963fe0c6856452))
* Add parser definition tests ([a27d0ab](https://github.com/vivliostyle/vfm/commit/a27d0ab83eb47245ac69e6d15fa91c7099c128c2))
* Add test codes ([34aa884](https://github.com/vivliostyle/vfm/commit/34aa8841fcbf53dc87c16177c6486b8dc60a11a1))


Changeset:
M CHANGELOG.md
 M package.json

? Commit (chore: release v1.0.0-alpha.11)? Yes
? Tag (v1.0.0-alpha.11)? Yes
? Push? Yes
? Create a pre-release on GitHub (Release 1.0.0-alpha.11)? Yes
? Publish @vivliostyle/vfm@next to npm? Yes
🔗 https://github.com/vivliostyle/vfm/releases/tag/v1.0.0-alpha.11
🔗 https://www.npmjs.com/package/@vivliostyle/vfm
🏁 Done (in 66s.)

#41 にて村上さんの許可を得たので publish も実施。結果として pre なので npm@next 向けに 1.0.0-alpha.11 がリリースされた。

[akabekobeko]

#44 のために手元で npm を一括更新したらテストがエラーになる。以下は調査メモ。

jest 26.1.0 to 26.6.3、ts-jest 26.1.1 to 26.4.4

metadata.ts の以下がエラーになる。

file.data = {
  ...file.data,
  ...yaml(node.value),
};

ymal が object 以外も返すのに Spread を利用しているのが原因。VS Code 上でも警告される。

src/plugins/metadata.ts:24:7 - error TS2698: Spread types may only be created from object types.

    24       ...yaml(node.value),
             ~~~~~~~~~~~~~~~~~~~

当初 typescript を 3.9.5 から 4.1.3 へ更新したことが原因だと予想していたが jest と ts-jest を更新することで発生。yaml の戻り値を if で明示的に object と型判定することで回避可能。これは妥当なエラーである。

[akabekobeko]

remark-parse 8.0.2 to 9.0.0

以下のような tokenizer の動的追加がすべてエラーになる。

const { blockTokenizers, blockMethods } = this.Parser.prototype;
blockTokenizers.fencedBlock = tokenizer;

エラーは以下。

TypeError: Cannot set property 'fencedBlock' of undefined

      61 |
      62 |   const { blockTokenizers, blockMethods } = this.Parser.prototype;
    > 63 |   blockTokenizers.fencedBlock = tokenizer;
         |                              ^
      64 |   blockMethods.splice(blockMethods.indexOf('text'), 0, 'fencedBlock');
      65 | };
      66 |

      at Function.mdast (src/plugins/fenced-block.ts:63:30)
      at Function.freeze (node_modules/unified/index.js:128:28)
      at Object.<anonymous> (tests/utils.ts:9:38)

remark-parse に破壊的な変更があったのかもしれない。この npm さえ更新しなければテストは通るのだが #44 対応に必要であり、また npm 依存管理としてもなるべく最新にしてゆきたいので継続調査する。

[akabekobeko]

新 remark-parse は #45 として対応する。

[akabekobeko]

2021/1/9 の開発者会議にて VFM v1.0 としては現行の remark-parse v8 で可能な範囲のみ対応することとした。remark-parse v9 以降は大きな変更が必要なため VFM v2.0 へ見送る。

[akabekobeko]

npm で next タグをつけずにリリースすることになったので

"scripts": {
  "release:pre": "release-it --preRelease --npm.tag=next"
}

を

"scripts": {
  "release:pre": "release-it --preRelease"
}

として実行してみる。

[akabekobeko]

コマンドを変更して #42 を merge した後、実行してみた。

$ npm run release:pre                                                                           [~/Documents/dev/vivliostyle/vfm]

> @vivliostyle/vfm@1.0.0-alpha.11 release:pre
> release-it --preRelease

WARNING No version found in npm registry. Assuming new package.

🚀 Let's release @vivliostyle/vfm (currently at 1.0.0-alpha.11)


Changelog:
# [1.0.0-alpha.12](https://github.com/vivliostyle/vfm/compare/v1.0.0-alpha.11...v1.0.0-alpha.12) (2021-01-11)


Changeset:
M CHANGELOG.md
 M package.json

? Commit (chore: release v1.0.0-alpha.12)? Yes
? Tag (v1.0.0-alpha.12)? Yes
? Push? Yes
? Create a pre-release on GitHub (Release 1.0.0-alpha.12)? Yes
? Publish @vivliostyle/vfm@alpha to npm? Yes
🔗 https://github.com/vivliostyle/vfm/releases/tag/v1.0.0-alpha.12
🔗 https://www.npmjs.com/package/@vivliostyle/vfm
🏁 Done (in 53s.)

しかし npmjs のページを見ると latest は 1.0.0-alpha.6 のままである。実際に npm i @vivliostyle/vfm してみても同様。 --npm.tag=next を削除するだけではダメらしい。継続調査する。

[akabekobeko]

以下が問題らしい。

Publish @vivliostyle/vfm@alpha to npm?

これだと @alpha タグでリリースとなる。--npm.tag=next を削除するのではなく --npm.tag=latest のほうがよい？

[akabekobeko]

以下の Versions ページを見ると実際に alpha としてリリースされていた。

• @vivliostyle/vfm - npm

コマンドを再実行するとやはり

Publish @vivliostyle/vfm@alpha to npm?

と聞かれたのでキャンセルしておく。ここが @latest になるよう調べる。

[akabekobeko]

#52 で対応した。--preRelease かつ latest にしたければ --npm.tag=latest でよいらしい。ついでにこれを反映するための PR と merge も操作できた。

現在は @uetchy さんも管理者なので PR の merge で approve を求められる。今回はとりあえず強制的に merge したが、今後どうするか検討が必要。

[akabekobeko]

#34 対応のため PR #55 を反映させた alpha.15 をリリースしたのだが release notes には列挙されていない。タグか何かを設定する必要があるらしい。

[MurakamiShinyu]

release notes には列挙されていない。

commit message を "feat: ..." などとすると反映されると思います。

[akabekobeko]

バグ修正だった場合はコミット メッセージに fix: をつけると反映されるようだ。

[akabekobeko]

おっとすれ違い。やはりコミット メッセージだったのですね。次から対応します。今回は手動で release notes へ反映させておきました。

[akabekobeko]

これも CONTRIBUTING.md に書いておいたほうがよいですね。

• feat: ... Features
• fix: ... Bug Fixes

のようですね。

[akabekobeko]

#63 で↑について対応することにした。コード修正の反映とリリースまで一通り運用するようになったので本 issue は close する。以降の開発作業は個別に issue をたてる。