READMEを更新＋α (#221)

* READMEを追記し，slack通知のワークフローの説明ファイルを追加 * ビルドエラーが起きたときの対処を記述 * 誘導を追記 * path間違えてた * Slack Appの部分の内容を追記 * CIとテンプレ生成の順番を変更
ritscc · Feb 11, 2022 · 70cfa53 · 70cfa53
1 parent 819dd59
commit 70cfa53
Show file tree

Hide file tree

Showing 3 changed files with 177 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -5,13 +5,19 @@
 
 セットアップ手順
 --------------------
-セットアップですべきことは，次の2つです．
+セットアップですべきことは，次の7つです．
 
-1. リポジトリのセットアップ
-2. テンプレートファイルとGitHubの課題の生成
-3. CIのセットアップ
+1. [リポジトリのセットアップ](#セットアップ手順)
+2. [CIのセットアップ](#ciのセットアップ)
+3. [テンプレートファイルとGitHubの課題の生成](#テンプレートファイルとissueの発行)
+4. [会員に対するアクセス許可](#会員に対するアクセス許可)
+5. [ブランチ保護ルールの作成](#ブランチ保護ルールの作成)
+6. [SlackAppのセットアップ](#slackappのセットアップ)
+7. [PRテスト](#prテスト)
 
-1つ目はリポジトリのセットアップです．以下の通りにセットアップしてください．
+リポジトリのセットアップ
+---------------------
+総会リポジトリ`soukai-{年度}-{回数}`を生成します．
 1. `$ git clone git@github.com:ritscc/soukai-template.git`
 でこのテンプレートをcloneしてください．（ここでフォークではないことに注意してください．）
 2. 自身のターミナルで `soukai-template` フォルダがあるディレクトリに移動してください．
@@ -30,23 +36,22 @@
 13. `$ mv .github.sample .github` を実行します．
 14. `$ git add -A` `$ git commit -m 'setup github actions'` `$ git push` を順に実行します．
 
-セットアップ作業の2つ目は，
-担当者が編集するファイルの間違いを少なくし，
-すべての担当部分を課題として管理できるようにするために必要です．
-これらの作業は，Pythonスクリプトと設定ファイルを用いることで，簡単に設定することができます．
-作業方法は，このあとの「setup.pyについて」や[README\_setup.md](docs/README_setup.md)をご覧ください．
-
-3つ目のCIとは，継続的インテグレーションのことです．
-設定を行うと，次のことがコミットのタイミングなどで自動的に行われるようになります．
-
-* 誤字や表記ゆれの指摘をGitHubのPull requestsにコメント
+CIのセットアップ
+-----------------------
+CIとは，継続的インテグレーション(Continuous Integration)のことです．
+設定を行うと，誤字や表記ゆれを，コミットのタイミングなどで，GitHubのPull requestsに，自動的に指摘してくれるようになります．
 
 人手でやることを減らせるので，設定することを推奨します．
-リポジトリを作成したら一番に設定しましょう．
-作業方法は，[README\_CI.md](docs/README_CI.md)をご覧ください．
+CIのセットアップ方法については，[README\_CI.md](docs/README_CI.md)に詳しく紹介しています．
 
-setup.pyについて
+テンプレートファイルとissueの発行
 ---------------------
+LaTeXのテンプレートファイルとissueの発行を行います．
+これらの作業は，担当者が編集するファイルの間違いを少なくし，
+すべての担当部分をissueとして管理できるようにするために必要です．
+これらの作業は[setup.py](setup/setup.py)を用いることで，簡単に設定することができます．
+
+### setup.pyについて
 年度などの初期設定をしたり，テンプレートファイルを生成するツールです．
 soukai-templateからコピーした直後や，各局のブランチを作るときに使ってください．
 
@@ -61,9 +66,11 @@ Pythonの動作環境は以下の通りです．
 $ pip install jinja2
 $ pip install pyyaml
 ```
-でインストールしてください
+でインストールしてください．
+詳しくは，[README\_setup.md](docs/README_setup.md)を見てください．
 
-soukai-templateからコピーした後の作業の大まかな流れは以下のようになります．
+### 作業手順
+カレントディレクトリが総会リポジトリになっていることを確認した上で，以下の手順を踏んでください．
 1. 以下のコマンドを実行して，年度などの情報を設定する．
     ```shell
     $ cd setup
@@ -84,10 +91,77 @@ soukai-templateからコピーした後の作業の大まかな流れは以下
 これはコンフリクトを避けるためです．
 タスクを作成する時に編集するべきファイルパスを明示しておくと混乱が減ると思われます．
 
-詳しくは，[README\_setup.md](docs/README_setup.md)を見てください．
+会員に対するアクセス許可
+-----------------------
+会員が総会リポジトリにpushできるようにします．
+1. 総会リポジトリの`Settings/Manage access`にアクセスします．
+2. `Invite teams or people`からアクセスを許可していきます．Roleは以下のようにしてください．
+    ```
+    SystemManagement : Admin
+    member20xx : Write
+    ```
 
-CIについて
+ブランチ保護ルールの作成
 -----------------------
-継続的インテグレーションを支援するサービスとしてGitHub Actionsが利用できます．
-これらを用いて，総会文書のビルドを自動化しています．
-CIのセットアップ方法については，[README\_CI.md](docs/README_CI.md)に詳しく紹介しています．
+シス管局員以外がmasterブランチやdevelopブランチにpushしないよう，ブランチ保護ルールを作成します．
+
+1. `$ git checkout -b develop`でdevelopブランチを作成し，`$ git push origin develop`でdevelopブランチをpushします．
+2. 総会リポジトリの`Settings/Branches`で`Default branch`を`develop`に変更します(初期は`master`)．右側にある矢印のアイコンをクリックすることで変更できます．
+3. `Branch protection rules`の隣の`Add rule`をクリックしてください．
+4. `Branch name pattern`に`develop`と入力し，以下の項目にチェックを入れて下さい．わからなかったら過去の総会リポジトリを参照してください．
+    * Require pull request reviews before merging
+        ```   
+        Require approving reviews : 3
+        ```
+    * Require status checks to pass before merging
+        * Require branches to be up to date before merging
+    * Restrict who can push to matching branches
+        ```   
+        People, teams or apps with push access : ritscc/systemmanagement
+        ```
+5. `Save changes`を押してください．
+6. 4を`master`にも同様に行う．
+
+SlackAppのセットアップ
+-----------------------
+Slack App(RCC soukai)のセットアップを行います．これは総会文書が
+
+1. `release`する (developブランチからmasterブランチへのPRを作成する)
+2. `pre-release`した後、`pre-release`を外す (リポジトリ右部の`Releases/Edit`で`This is a pre-release`のチェックを外す)
+
+という手順を踏んだときに，Slackの`#soukai`にメッセージを投稿するアプリです．
+
+### 作業手順
+Slack Appをそのまま使う場合は以下の手順を踏んで下さい．[README_notify.md](docs/README_notify.md)を見て作り直してもいいですが，Scrapbox(ritscc-private)の`Slack App Webhook URL`の内容は必ず更新してください．
+
+1. Webhook URLをScrapbox(ritscc-private)から取得します．`Slack App Webhook URL`というタイトルの記事に記載されています．
+
+2. `Settings/Secrets/New repository secret`にWebhook URLを保存します．この時、Name属性は必ず`SLACK_WEBHOOK`にしてください。
+    ```
+    Name : SLACK_WEBHOOK
+    Value : 取得したWebhook URL
+    ```
+
+3. (任意)投稿メッセージのカスタマイズをします．以上の作業では、下記のようなメッセージが投稿されることになります。
+
+<img width="418" alt="スクリーンショット 2021-08-27 12 47 42" src="https://user-images.githubusercontent.com/50389029/131068908-1569e6a9-a0a0-4257-8617-fee94e7b6d92.png">
+
+`Message`というテキストを変更したい場合は、`.github.sample/workflows/notify.yml`を下記のように変更してください。
+
+```diff
+    env:
++   SLACK_TITLE: "タイトルを記入するよ"
+    SLACK_MESSAGE: ":tada: 総会文書がリリースされました"
+    SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
+```
+詳しくは[action-slack-notify](https://github.com/rtCamp/action-slack-notify)を見てください．
+
+PRテスト
+-----------------------
+最後にPRテストを行います．
+
+1. 総会文書の作成手順にしたがって適当なファイルを編集します．
+2. developへのPRを作成し，GitHub Actionsが適切に動作するか確認します．ビルドエラーが起きた場合は[README_builderror.md](./docs/README_builderror.md)を見てください．
+3. 成功したらSlackで総会リポジトリ生成の旨を伝え，執筆作業を開始してもらいます．
+
+総会リポジトリの設定は以上です．
diff --git a/docs/README_builderror.md b/docs/README_builderror.md
@@ -0,0 +1,23 @@
+LaTeXのBuildに失敗したとき
+=====================
+2021年9月現在までで確認されている原因として
+* [entrypoint.sh](/.github.sample/actions/latex/entrypoint.sh)に権限がない
+
+というものがありました(一応これはDockerfileの変更により修正されたはずですが)．
+
+entrypoint.shに権限がない
+--------------------
+
+ 解決するには以下のコマンドを順に実行してください．
+ ```
+$ git checkout develop
+$ git config core.filemode=true
+$ chmod +x entrypoint.sh
+$ git add entrypoint.sh
+$ git commit(以下略)
+$ git push origin develop
+$ git config core.filemode=false
+$ git checkout (テストのときに作ったブランチ)
+$ git pull origin develop
+ ```
+以上のことをした後，もう一度テストをするとBuildに成功すると思います．
diff --git a/docs/README_notify.md b/docs/README_notify.md
@@ -0,0 +1,55 @@
+# リリース時にSlackに通知するワークフロー
+
+[notify.yml](../.github.sample/workflows/notify.yml)はGitHubのreleaseイベントをトリガーに、ビルドの成功を通知するワークフローです．
+
+> [pre-releaseの場合は通知しないようにして、pre-releaseを後から外した時にactionが走ってくれると最高.](https://github.com/ritscc/soukai-template/issues/203)
+
+とのことなので、
+
+1. `release`する
+2. `pre-release`した後、`pre-release`を外す
+
+の時に発火するよう設定しています。
+
+## セットアップ時に必要なこと
+
+前提として、**通知先のチャンネル**と**通知するSlack App**が必要です。
+
+Slackへの通知には[Incoming Webhook](https://slack.com/intl/ja-jp/help/articles/115005265063-Slack-%E3%81%A7%E3%81%AE-Incoming-Webhook-%E3%81%AE%E5%88%A9%E7%94%A8)を使用しており、通知先チャンネルのWebhook URLが必要なので一応説明しておきます。
+
+### 1. Slack Appを作成
+
+[Your apps](https://api.slack.com/apps)から作成できます。
+
+### 2. Webhook URLを取得
+
+Appを作成したら、`Add New Webhook to Workspace`から通知先チャンネルのWebhook URLを取得してください。
+
+```
+curl -X POST -H 'Content-type: application/json' --data '{"text":"Hello, World!"}' <取得したWebhook URL>
+```
+
+を実行すると、連絡先チャンネルに`Hello, World!`のメッセージが投稿されるはずです。
+
+### 3. SecretsにWebhook URLを保存
+
+作成した総会リポジトリの`Settings > Secrets > New repository secret`からWebhook URLを保存できます。この時、Name属性は必ず`SLACK_WEBHOOK`にしてください。
+
+![](https://user-images.githubusercontent.com/50389029/131068750-7e315077-a5e3-478e-8f44-ac0a3fc64e57.png)
+
+## 投稿メッセージのカスタマイズ
+
+以上の作業を終えると、下記のようなメッセージが投稿されることになります。
+
+<img width="418" alt="スクリーンショット 2021-08-27 12 47 42" src="https://user-images.githubusercontent.com/50389029/131068908-1569e6a9-a0a0-4257-8617-fee94e7b6d92.png">
+
+`Message`というテキストを変更したい場合は、`.github.sample/workflows/notify.yml`を下記のように変更してください。
+
+```diff
+  env:
++   SLACK_TITLE: "タイトルを記入するよ"
+    SLACK_MESSAGE: ":tada: 総会文書がリリースされました"
+    SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+詳しくは[action-slack-notify](https://github.com/rtCamp/action-slack-notify)