開発再開メモ

Question

開発再開メモ

Closed this issue 4 years ago · 30 comments

akabekobeko commented 4 years ago

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

Answer 1 · 2020-12-08T06:12:22.000Z

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

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

Answer 2 · 2020-12-08T06:47:02.000Z

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 でも開発してゆけそう。

Answer 3 · 2020-12-08T06:49:11.000Z

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

Answer 4 · 2020-12-08T06:53:54.000Z

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

Answer 5 · 2020-12-08T07:37:05.000Z

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

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

git clone したリポジトリーの master へ直に commit/push

git clone したリポジトリーにローカルで作業ブランチを追加して Pull Request 作成 & merge

fork したリポジトリーの master へ直に commit/push して GitHub 上で本家に対して Pull Request 作成

fork したリポジトリーに作業ブランチを追加して commit/push 後、GitHub やなんらかのクライアント (CLI や SourceTree) で Pull Request 作成

その他

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

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

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

Answer 6 · 2020-12-08T07:38:22.000Z

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

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

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

Answer 7 · 2020-12-08T07:42:42.000Z

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

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

Answer 8 · 2020-12-08T07:59:55.000Z

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

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

Answer 9 · 2020-12-10T06:55:06.000Z

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

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

Answer 10 · 2020-12-15T14:40:05.000Z

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

Answer 11 · 2020-12-15T14:45:43.000Z

#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 も見られる。

Answer 12 · 2020-12-15T14:54:13.000Z

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 設定ではないのかもしれない。

Answer 13 · 2020-12-16T00:47:55.000Z

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 関連の環境設定が必要らしい。

Answer 14 · 2020-12-16T07:31:07.000Z

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

Configure github.release: true これは VFM リポジトリー内の .release-it.json に設定済み
Obtain a personal access token... 自分のアカウントに対して生成するものなのでリンク先で生成
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 操作が必要なのだろうか？継続調査する。

Answer 15 · 2020-12-16T07:41:29.000Z

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 がリリースされた。

Answer 16 · 2020-12-21T07:00:36.000Z

#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 と型判定することで回避可能。これは妥当なエラーである。

Answer 17 · 2020-12-21T07:06:43.000Z

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 依存管理としてもなるべく最新にしてゆきたいので継続調査する。

Answer 18 · 2020-12-21T08:29:38.000Z

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

Answer 19 · 2021-01-10T09:01:09.000Z

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

Answer 20 · 2021-01-11T07:07:24.000Z

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

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

を

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

として実行してみる。

Answer 21 · 2021-01-11T07:26:53.000Z

コマンドを変更して #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 を削除するだけではダメらしい。継続調査する。

Answer 22 · 2021-01-11T07:48:02.000Z

以下が問題らしい。

Publish @vivliostyle/vfm@alpha to npm?

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

Answer 23 · 2021-01-11T07:50:22.000Z

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

@vivliostyle/vfm - npm

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

Publish @vivliostyle/vfm@alpha to npm?

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

Answer 24 · 2021-01-11T08:16:46.000Z

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

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

Answer 25 · 2021-01-14T09:41:36.000Z

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

Answer 26 · 2021-01-14T09:46:12.000Z

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

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

Answer 27 · 2021-01-14T09:46:19.000Z

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

Answer 28 · 2021-01-14T09:47:14.000Z

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

Answer 29 · 2021-01-14T09:48:24.000Z

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

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

のようですね。

Answer 30 · 2021-01-16T12:21:50.000Z

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