よこなのへたのよこずき

noteもよろしくね

key=value をファイルに羅列しシェル変数を一気に適用する( . ドットコマンドを使う)

あるファイルが

  • exampleという名前で
  • 中身が
key1=value1
key2=value2
key3=value3

の時

. /path/to/example

(↑小さいけど先頭にピリオドがあるよ!)

って実行すれば key1, key2, key3はシェル変数として登録されることを知った。

$ echo $key1
value1

$ echo $key2
value2

$ echo $key3
value3

. はカレントシェルでファイルの中身を実行するという意味らしい。なので、もちろん用途はシェル変数の作成に留まらずコマンドが実行できる。 つまりsourceコマンドと同じ役割なんだけど、sourceコマンドはbashでしか使えない(shでは無理)らしい。

ソースコードコメント少なめの文化に触れている。しばらく試してみよう

見ているプロジェクト、自分の感覚では結構ソースコードコメントがない(皆無ってわけじゃないけど体感少ない)。前職は金融系ではちゃめちゃに複雑な業務知識が多かったのもあるけど、皆で丁寧にコメントやドキュメントを書きまくる文化があった。クラスやフィールドの説明も全部あったし、メソッドにもどういう理由で何がしたいかとかwikiへのリンクとかが添えられていた記憶がある。

今は

  • コメントを書くより命名やテストでやりたいことを示そう
  • コミットログやGitHubで辿れる履歴を見ながらチームで話そう
  • コメントとソースコードが乖離した場合、コメントがないよりもマズい

などの理由でソースコードコメントがあまりない。少なくとも前の組織に比べると。あ、ちなみにコードとは別に、ドキュメントは積極的に作成する風潮がしっかりある。

私はソースコードコメント書きまくるの肯定派だった(ので上について聞いてみたのだ)けど、話してみると

  • コメント書く派:命名やロジックの工夫でメンテナビリティ保てるのが理想。でも現実的には情報が落ちちゃうからコメントも必要だよね
  • 一方書かない派:コメントがロジックを追従して綺麗に維持できるのが理想。でも現実的には乖離するから命名とかで頑張るしかないよね

ということなのかなと考える。今のところチームは後者寄りのスタンス。

これまで私が書く派全力推しだったのは何故だか考えてみると、「乖離しちゃう」課題は乗り越えられると思っていたからだ。コメントを残す合意さえあれば、遅くともレビューの時点で更新漏れに気付ける。このペインポイントは十分カバーできるし、時間や労力はかかっても多くの人が関わって長くプロジェクトを続けたいなら得られるものの方が大きいという主張を持っていたのだと思う。

この議論についてはTwitterとかでも散々されていると思うんだけど改めて考える機会が来たというお話でしたん。

幸い前述の通りドキュメントはがんがん残そうどんどん共有しようという文化なので、それと合わせてコメントについては上記の方針でやっていくとどんな経験をするか、しばらく試してみることにする。日々、皆と色々相談しながらやっていくよー!

ちょっとした疑問をスルーしない能力、発揮していきたい

ここ3日、チームに小さい疑問を持ちこんで皆に色々教えてもらったり議論したりした。抽象的な書き方になっちゃうけど、

  • 今2つのリポジトリで管理しているものたち、マージしたほうが都合がいいんじゃないか?
  • issueの内容に納得して実装を終えたけど、レビューで別の方法がいいんじゃないかという指摘が来たよ。確かにそれも一理あるので方向性皆で決めたいな
  • バラバラな呼ばれ方してる言葉があるので統一しようよ

といった、ちょっと「ん?」と思うような、でも大事なことたちである。

ihcomega.hatenadiary.com

この記事にも書いたとおり、1on1が盛んな一方で、大事な情報や改善ポイントがその2人だけに閉じてしまうことが結構あったので「何でもシェアする」が最近のテーマ。

例えば1つ目は結局マージしないことになったんだけど、私が「都合がいい」と思った点について、リポジトリのマージ以外で解決する方法を皆で見出したので良かった。3つ目の用語の統一については、何故バラバラな呼び方になっているのかが分かったのでどう統一するか決めやすく、プロジェクトが1番参考にしているライブラリの呼び方に近付けようということになった。

やっぱり話さないと背景や理由が分からないことってよくある。そして、長くいるメンバーからはどうしてもそういう話が上がりにくくなるし、新入りでかつ性格的にも小さいことを気にしがちな自分はこうして声を上げるのが向いている気がする。というか、自分が特に細かいというより、日本人は平均的に「気付き力」が高いんじゃないかなっていう気がしなくもない。もちろん一概には言えないけど。

ちなみにこういうのを思いついた時すぐSlackに書いても何の反応もなかったりしてカルチャーショックなんだけど笑、口頭で相談できる場に持ち込んだ方が皆ちゃんと意見をくれると分かった。「いい話し合いが出来たな」という気持ちを積み重ねることで、英語で相談を持ちかけることにも抵抗がなくなっていくのを感じるー!

Windowsでwgetをインストールして使う(想像の1.2倍大変)

まだ赤ちゃんの自プロジェクト、Windowsではろくに動かないので学生さんと一緒に地道に対応している最中。今日はwgetコマンドが使えなかった。新しめのOS x PowerShellならInvoke-WebRequestっていうコマンドのaliasとしてwgetがあるという話も見たのだけど、npm startした時にコマンドがないと怒られた。よく分からない。

www.jcchouinard.com

インストール方法は↑本当にここに書いてあるとおりで

  1. GNU Wget 1.21.3 for Windows にてexeファイルをダウンロードする
  2. exeをC:\Windows\System32フォルダに移動する。なお、コマンドプロンプトpathって打ってこのフォルダにパスが通っていることを確認するとより安全
  3. コマンドプロンプトを立ち上げ(直し)たら使える

という流れなんだけど、思ったよりは大変。パス通すという作業の存在を先週くらいに思い出した。 ただ、調べるとWindowsにもPackage Managerがあるのね?試します。あとWSL2も動かしてみます。

GitHub Actionsが特定のイベントでfailした時だけSlackに通知する

ちょっと前に取り組んだのでメモしておきます。GitHub Actionsの話ばっかり書いている…

2つの実現方法

GitHub Actionsの結果をSlackに通知する方法は2つあります。

ざっくりいうと視点が逆という感じなんですが、それぞれにpros/consがあります。

  • GitHub integration for Slack
    • メリット: 導入がめちゃくちゃ楽。Slackでsubscribeコマンドを打つだけで成形されたメッセージを受け取れる
    • デメリット: Actionsの結果による制御ができない(つら)。失敗だけ通知するとか、結果に応じてチャンネルを変えるとか無理
  • Slack app
    • メリット: 自分でGitHub Actionsのyamlを書いて細かい制御ができる
    • デメリット: GitHub integrationに比べると導入が面倒

GitHub integration for Slackを使う場合の設定

前述の通り細かい制御は不可能なので、こっちはタイトルとずれた内容になります(タイトル通りのことは後半に)。

  1. Slackにインテグレーションを追加する
  2. /github subscribe <organization>/<repository> workflows:{name:"<workflow name>" event:<events> branch:"<branch>"}を実行する
  3. 不要な更新も追加されてしまったらunscribeする

例えば上記は

/github subscribe ihcomega56/github-actions-failure-test workflows:{name:“Integration Tests” event:“schedule”,“push” branch:“main”}

としています。これは

  • ihcomega56/github-actions-failure-testリポの
  • Integration Testsワークフローが
  • 定期実行(schedule)またはmainへのpushにより

実行された場合、結果を通知せよと言っています。

そして、上の画像のようにインテグレーションくんがissueやPRなどの更新もすべてキャッチしようとしてしまったら、要らないものは外します。ワークフローの通知以外は不要だとすると、

/github unsubscribe ihcomega56/github-actions-failure-test issues pulls commits releases deployments

を叩くと、スペース区切りで指定した機能はまとめてオフになります。

設定値の詳細はぜひ公式へ: github.com

ということで、これだけで見た目もいい感じのメッセージが受け取れるようになるのでお手軽便利です。1実行につき、ワークフローが走り始めた時・終わった時の2回通知が来ます。

ちなみにこの拡張のリポジトリはコントリビューションを受け付けておらず、機能改善したい際はお願いすることだけが許されています。通知を失敗時だけにしたいよ!というissueも既に存在するので、欲しい方はいいねしましょう!!!!!

github.com

もうひとつ補足として、(un)subscribeはチームの誰が実行してもいいと思います。SlackとGitHubに十分な権限*1さえあれば、Aさんが登録したものをBさんが解除みたいなことも出来るため、チームリーダーやadminっぽい人に頼まなくて大丈夫なはずです。

Slack appを使う場合の設定

自分のチームでは結果に応じてチャンネルを振り分けたいということになったので設定ファイルを書きました。

github.com (↑最終的には1つ目の方法に変わったのでマージされてないけど、実際のPR)

ポイントを抜粋すると、GitHub Actionsに下記のようなステップたちを追加します。日本語のコメントはこのブログ用に解説としてつけたものです。
※インデントは左に詰めてあるのでこのままだと動きません

# トリガーたち。これらのうち、定期実行およびmainへの更新時のみ通知したい
# (例えばPRのオープン時とかは要らない。通知されなくともマージするまで何度も見るので)
on:
  schedule:
    # scheduled at 3PM and 3AM daily
    - cron: '0 3,15 * * *'
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - ready_for_review
      - closed
# Send the result to Slack when a PR is merged and tests were executed regularly
- name: Notify success
  # 成功した && 定期実行かmain更新がされた場合、下記を走らせる
  if: ${{ success() && contains(fromJson('["push", "schedule"]'), github.event_name) }}
  uses: slackapi/slack-github-action@v1.23.0
  with:
    # 成功通知用のチャンネルIDをsecretsに追加しておく
    channel-id: ${{ secrets.CHANNEL_ID_FOR_MESSAGES }}
    # If https://github.com/slackapi/slack-github-action/issues/84 is fixed, payload.json can be shared among the following two steps (DRY).
    payload: |
      {
        "text": "Integration tests finished successfully.",
        "attachments": [{
        "title": ":white_check_mark: ${{ github.workflow }} #${{ github.run_number }}",
        "title_link": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}",
        "color": "#36a64f"
        }]
      }
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

- name: Notify failure
  # 失敗した && 定期実行かmain更新がされた場合、下記を走らせる
  if: ${{ failure() && contains(fromJson('["push", "schedule"]'), github.event_name) }}
  uses: slackapi/slack-github-action@v1.23.0
  with:
    # 失敗通知(アラート)用のチャンネルIDをsecretsに追加しておく
    channel-id: ${{ secrets.CHANNEL_ID_FOR_ALERTS }}
    payload: |
      {
        "text": "Integration tests failed. Check the following workflow and fix it.",
        "attachments": [{
        "title": ":x: ${{ github.workflow }} #${{ github.run_number }}",
        "title_link": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}",
        "color": "#ff0000"
        }]
      }
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

(なんかyamlの解析うまくいってなくて表示おかしいかもw)

補足すると

  • github.event_namepush, pull_requestなどイベントによる振り分けに使える。1つだけならイコール==でいけるが、複数の場合は上記のようにfromJsonなどと書く(参考: 公式docたち GitHub Actions のワークフロー構文 - GitHub Docs, 式 - GitHub Docs
  • Slackにメッセージを送るのは公式のアクションを使っている
  • SlackのチャンネルIDはチャットのURLから取れる。ブラウザで希望のチャンネルにアクセスするとhttps://app.slack.com/client/<スペースのID>/<チャンネルのID>ってなってるので、最後のスラッシュ以降をコピペすればOK。他にもっと良い取得方法があるのかもしれないけど
  • payloadでSlackのレイアウトを指定する。結構複雑なこともできるけど、今回は極めてシンプルに結果とActionsへのリンクだけ埋め込んでいる
  • bot tokenをSlackのコンソールで生成する。READMEにも説明があるので、参考スクショだけ貼っておく…↓*2

設定をいじりたいbotをクリックするとこの画面に辿り着けるよ!

ここまで設定するとこんな感じで結果が送られてきます!

画像にはないけどチャンネル振り分けもできました。

結論

Notify workflows only on errors · Issue #1563 · integrations/slack · GitHub が実装されれば面倒なことしなくてもすべて解決や・・・🙏

御礼

twitter.com

こちらで相談乗ってくださったよしことしろやまさんありがとうございましたー!

*1:あんまりちゃんと調べていないので「十分」とボカしておきます…例えば、GitHubはread権限だけでいいのかもしれないけど分からん

*2:私はどうもSlackで欲しいトークンとかを見つけるのが苦手なんだけど皆はどうですか…。コンソール妙にむずくない?

Dependabotってスコープとか頻度とか設定できるんだね

GtiHubがボランティア(?)で勝手に動かしてくれてるだけのアンコントローラブルなものだと思ってた…w

docs.github.com

dependabot.yml を追加しておくと設定変えられるんですね。弊プロジェクトにはこんな記述がありました(一部抜粋)。

- package-ecosystem: "cargo"
  directory: "/"
  open-pull-requests-limit: 1
  schedule:
    interval: "daily"

これでCargoのパッケージに対して1日1回スキャンしてくれると。 open-pull-requests-limit はそのリポジトリ内にdependabotが最大いくつのPRを作れるか(デフォルトは5)という意味らしいです。PR一覧のページがdependabotの指摘で埋まらないように出来るんですね。

まぁそうなる前に対応しよう!

パッケージ(アーティファクト)のセキュリティに着目しようねっていう話をデベロッパーアドボケイト時代に山程していた私より。

日本の英語教育で培った読み書き力でwikiを作成する日々

github.com

今日送ったPR↑ テストについて説明するページを追加した。

毎日MTGでは上手く議論や説明ができなくてしんどいけど、読み書きは比較的心穏やかに取り組める。ただし、スピードはもちろん課題なので翻訳AIになるべく頼らず訓練していきたい。

言語は違えどwikiで気をつけることは同じで、まず結論や概要を分かりやすく示すとか、メンテナンスしやすいよう心がける(オレオレな図とか差し込むと編集が大変なのでなるべくmermaid記法とかを使う*1)とかが当然大事。

その上で英語のライティングにおける注意点として出来る限り気をつけているのは

  • 同じ表現を繰り返さない - 少しでも稚拙さを減らすため
    • まず単語をばらけさせる。例えばテストにおける確認を表すなら、test / check / verify / confirm / make sure あたりを使い回す。どれも簡単な単語だからやりやすいでしょ!
    • 同じ主語ばかり使わないというのもある。We execute testsじゃなくてTests are executedにするみたいな
  • フォーマルな書き言葉を目指す
    • これは受験勉強で培ったスキルがそのままいかされており、日本人は…というと主語がでかいけど、結構自信を持てるパートかもしれない。我々とは反対で、ペラペラだけど書くのはそんなに得意じゃない人もいるしね
    • エディタやブラウザがミスを指摘していたら無視せず向き合う

ちなみに、皆が良く使う開発英単語みたいなのはやっぱり現地にいると学びやすい。今のところすごく聞くなぁと感じるのは

  • investigate - 調査する
  • reproduce - 再現する
  • for now - いったん

とか。当たり前だけど開発の現場はどこも似たような会話をしているのである。for nowすき。ベストじゃないけど「いったんこれで!」ってまぁ言いますよね。こっちでも、"It's okay for now." "We can choose this way for now." はあるある…w

*1:実はこれ過去の職場で途中までまったく意識できてなかったため反省していることのひとつ