From 92db204794224c72c053a75bc2c560b0d1b3888b Mon Sep 17 00:00:00 2001 From: Yosuke Ota Date: Thu, 19 Dec 2024 20:43:21 +0900 Subject: [PATCH] Repository Maintenance (#186) --- .eslintrc.js | 7 - .github/workflows/ci.yml | 7 +- .npmrc | 3 +- .prettierrc | 4 + .vitepress/config.mjs | 26 +- .vitepress/theme/components/PageInfo.vue | 2 +- .vscode/settings.json | 8 +- ...75\345\220\215\350\246\217\347\264\204.md" | 13 +- documents/forAWSResource/index.md | 2 +- documents/forGitBranch/commit_message_rule.md | 174 ++++---- .../forGitBranch/git_branch_standards.md | 54 +-- documents/forGitBranch/index.md | 2 +- .../forGitBranch/merge_develop_to_feature.md | 98 ++--- .../forGitBranch/merge_feature_to_develop.md | 146 +++---- documents/forGitBranch/vscode_git_ope.md | 202 ++++----- documents/forJava/index.md | 2 +- ...IF\345\256\232\347\276\251\346\233\270.md" | 28 +- .../UIM01/index.md" | 2 +- .../01_\347\224\273\351\235\242/index.md" | 2 +- .../docs/02_WebAPI/openapi.yaml | 398 +++++++++--------- .../future_muscle_partner/docs/README.md | 4 +- documents/forMarkdown/index.md | 2 +- ...70\350\250\255\350\250\210\346\233\270.md" | 6 +- .../OpenAPI_Specification_2.0.md | 18 +- .../OpenAPI_Specification_3.0.3.md | 236 +++++------ documents/forOpenAPISpecification/index.md | 2 +- .../sample_divided/common/responses.yaml | 52 +-- .../examples/pets_get/test_case_001.yaml | 68 +-- .../examples/pets_get/test_case_002.yaml | 4 +- .../pets_pet_id_get/test_case_003.yaml | 16 +- .../sample_divided/openapi.gen.yaml | 46 +- .../sample_divided/openapi.yaml | 2 +- .../sample_divided/pets/pets.yaml | 334 +++++++-------- .../sample_divided/pets/pets_pet_id.yaml | 106 ++--- documents/forSQL/index.md | 2 +- documents/forSlack/index.md | 2 +- documents/forSlack/slack_usage_guidelines.md | 165 ++++---- eslint.config.mjs | 29 ++ index.md | 4 +- package.json | 14 +- 40 files changed, 1159 insertions(+), 1133 deletions(-) delete mode 100644 .eslintrc.js create mode 100644 .prettierrc create mode 100644 eslint.config.mjs diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index b0746ef4..00000000 --- a/.eslintrc.js +++ /dev/null @@ -1,7 +0,0 @@ -module.exports = { - extends: ["standard", "plugin:vue/recommended", "prettier"], - rules: { - "no-var": "error", - "prefer-const": "error", - }, -}; diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 26615daf..ec504802 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,7 +5,7 @@ on: branches: [master] jobs: - build-docs: + build-and-lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -13,6 +13,9 @@ jobs: - name: Install Packages run: | npm i -f - - name: Build all + - name: Lint + run: | + npm run lint + - name: Build run: | npm run build diff --git a/.npmrc b/.npmrc index 9cf94950..1d83df99 100644 --- a/.npmrc +++ b/.npmrc @@ -1 +1,2 @@ -package-lock=false \ No newline at end of file +package-lock=false +force=true \ No newline at end of file diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 00000000..222861c3 --- /dev/null +++ b/.prettierrc @@ -0,0 +1,4 @@ +{ + "tabWidth": 2, + "useTabs": false +} diff --git a/.vitepress/config.mjs b/.vitepress/config.mjs index 7d6bf22c..87fad4a8 100644 --- a/.vitepress/config.mjs +++ b/.vitepress/config.mjs @@ -16,7 +16,7 @@ const repoUrl = pkg.repository.url /** @type {import("vitepress").DefaultTheme.Sidebar} */ const links = { "/documents/forJava/": [ - { text: "Home", link: "/documents/forJava/" }, + { text: "Introduction", link: "/documents/forJava/" }, { text: "Javaコーディング規約", link: "/documents/forJava/Javaコーディング規約.html", @@ -31,7 +31,7 @@ const links = { }, ], "/documents/forSQL/": [ - { text: "Home", link: "/documents/forSQL/" }, + { text: "Introduction", link: "/documents/forSQL/" }, { text: "SQLコーディング規約（PostgreSQL）", link: "/documents/forSQL/SQLコーディング規約（PostgreSQL）.html", @@ -42,14 +42,14 @@ const links = { }, ], "/documents/forAWSResource/": [ - { text: "Home", link: "/documents/forAWSResource/" }, + { text: "Introduction", link: "/documents/forAWSResource/" }, { text: "AWSインフラ命名規約", link: "/documents/forAWSResource/AWSインフラリソース命名規約.html", }, ], "/documents/forOpenAPISpecification/": [ - { text: "Home", link: "/documents/forOpenAPISpecification/" }, + { text: "Introduction", link: "/documents/forOpenAPISpecification/" }, { text: "OpenAPI Specification 2.0規約", link: "/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.html", @@ -60,7 +60,7 @@ const links = { }, ], "/documents/forGitBranch/": [ - { text: "Home", link: "/documents/forGitBranch/" }, + { text: "Introduction", link: "/documents/forGitBranch/" }, { text: "Gitブランチフロー規約", link: "/documents/forGitBranch/git_branch_standards.html", @@ -83,7 +83,7 @@ const links = { }, ], "/documents/forSlack/": [ - { text: "Home", link: "/documents/forSlack/" }, + { text: "Introduction", link: "/documents/forSlack/" }, { text: "Slack利用ガイドライン", link: "/documents/forSlack/slack_usage_guidelines.html", @@ -152,7 +152,7 @@ export default defineConfig({ text: "Java", items: [ { - text: "Home", + text: "Introduction", link: "/documents/forJava/", }, { @@ -173,7 +173,7 @@ export default defineConfig({ text: "SQL", items: [ { - text: "Home", + text: "Introduction", link: "/documents/forSQL/", }, { @@ -193,7 +193,7 @@ export default defineConfig({ text: "AWS インフラリソース", items: [ { - text: "Home", + text: "Introduction", link: "/documents/forAWSResource/", }, { @@ -206,7 +206,7 @@ export default defineConfig({ text: "OpenAPI Specification規約", items: [ { - text: "Home", + text: "Introduction", link: "/documents/forOpenAPISpecification/", }, { @@ -223,7 +223,7 @@ export default defineConfig({ text: "Gitブランチフロー規約", items: [ { - text: "Home", + text: "Introduction", link: "/documents/forGitBranch/", }, { @@ -236,7 +236,7 @@ export default defineConfig({ text: "Markdown設計ドキュメント規約", items: [ { - text: "Home", + text: "Introduction", link: "/documents/forMarkdown/", }, { @@ -249,7 +249,7 @@ export default defineConfig({ text: "Slack利用ガイドライン", items: [ { - text: "Home", + text: "Introduction", link: "/documents/forSlack/", }, { diff --git a/.vitepress/theme/components/PageInfo.vue b/.vitepress/theme/components/PageInfo.vue index 207d96fd..960e69b0 100644 --- a/.vitepress/theme/components/PageInfo.vue +++ b/.vitepress/theme/components/PageInfo.vue @@ -60,7 +60,7 @@ export default { }, }, mounted() { - if(import.meta.env.SSR) return; + if (import.meta.env.SSR) return; loadScript(); }, }; diff --git a/.vscode/settings.json b/.vscode/settings.json index ffacf933..f29488c1 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,9 +1,13 @@ { "eslint.validate": ["javascript", "javascriptreact", "vue"], - "eslint.workingDirectories": ["./", "./.vitepress"], "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" }, "editor.defaultFormatter": "esbenp.prettier-vscode", - "editor.formatOnSave": true + "editor.formatOnSave": true, + "[markdown]": { + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true + }, + "markdown.extension.tableFormatter.enabled": false } diff --git "a/documents/forAWSResource/AWS\343\202\244\343\203\263\343\203\225\343\203\251\343\203\252\343\202\275\343\203\274\343\202\271\345\221\275\345\220\215\350\246\217\347\264\204.md" "b/documents/forAWSResource/AWS\343\202\244\343\203\263\343\203\225\343\203\251\343\203\252\343\202\275\343\203\274\343\202\271\345\221\275\345\220\215\350\246\217\347\264\204.md" index 2768624f..030d1930 100644 --- "a/documents/forAWSResource/AWS\343\202\244\343\203\263\343\203\225\343\203\251\343\203\252\343\202\275\343\203\274\343\202\271\345\221\275\345\220\215\350\246\217\347\264\204.md" +++ "b/documents/forAWSResource/AWS\343\202\244\343\203\263\343\203\225\343\203\251\343\203\252\343\202\275\343\203\274\343\202\271\345\221\275\345\220\215\350\246\217\347\264\204.md" @@ -18,11 +18,10 @@ head: ::: warning 有志で作成したドキュメントである -* フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している +- フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している ::: - ## 前提条件 - 開発チームが 3 ～ 30 名程度で構築する規模での利用を想定している @@ -835,11 +834,11 @@ IAM グループ用のポリシーを作成する例では、company を含め | Category | Tag Key | Required | Note | | ------------ | ------- | -------- | ------------------------------------------------------------------------ | -| Common | Env | ✅ | 環境識別子 | -| | System | ✅ | システム名 | -| | Name | ✅ | リソースの識別子として機能名などを設定 | -| 費用按分 | Owner | ✅ | リソースの管理主管部署。費用の負担先を想定 | -| | Project | ✅ | 開発担当チーム。どのチームがどれくらい利用したかをトレースするために設定 | +| Common | Env | ✅ | 環境識別子 | +| | System | ✅ | システム名 | +| | Name | ✅ | リソースの識別子として機能名などを設定 | +| 費用按分 | Owner | ✅ | リソースの管理主管部署。費用の負担先を想定 | +| | Project | ✅ | 開発担当チーム。どのチームがどれくらい利用したかをトレースするために設定 | | ツールで利用 | StartAt | | 起動時刻。自動化ツールなどで必要があれば設定 | | | EndAt | | 停止時刻 | diff --git a/documents/forAWSResource/index.md b/documents/forAWSResource/index.md index 3c874230..c7107840 100644 --- a/documents/forAWSResource/index.md +++ b/documents/forAWSResource/index.md @@ -3,7 +3,7 @@ sidebarDepth: 4 author: フューチャー株式会社 layout: home hero: - name: AWSインフラ命名規約 + name: AWSインフラ命名規約 tagline: Future Enterprise Naming Convention Standards for AWS infrastructure resource actions: - theme: brand diff --git a/documents/forGitBranch/commit_message_rule.md b/documents/forGitBranch/commit_message_rule.md index af4e8142..9ad39680 100644 --- a/documents/forGitBranch/commit_message_rule.md +++ b/documents/forGitBranch/commit_message_rule.md @@ -1,87 +1,87 @@ ---- -sidebarDepth: 4 -title: コミットメッセージ規約 -author: フューチャー株式会社 ---- - -# コミットメッセージ規約 - -Gitのコミットメッセージにの書式についてルール化することで、コミットの目的がわかりやすくなる、履歴からのトラッキングの容易になる利点がある。 - -本規約のコミットメッセージの書式としては、`Conventional Commits`をベースとした規約としている。 - -以下の形式でコミットメッセージを記載することとする。 - -```md -: -``` - -コミットメッセージは -type、subject、gitmojiの最大3つの要素から構成され、それぞれは後述する書式に従うものとする。 -この中でも、type、subjectについては必須とし、ほかの要素についてはプロジェクトの運用にしたがい任意とする。 - -## type - -typeについては必須の要素となり、以下のいずれかを選択するものとする。 - -| type | 説明 | -|--------|--------------------------------------------------------------------------------------| -| `feat` | 新機能の追加 | -| `fix` | バグの修正 | -| `docs` | ドキュメンテーションの更新 | -| `refactor` | リファクタリング| - -## subject - -subjectについては必須の要素となり、変更内容を簡潔に記載するものとする。 -issue idについては、PRから参照する運用を想定し、コミットメッセージの必須要素とはしないこととする。 - -## gitmoji - -gitmojiについては任意の要素となり、変更内容を視認しやすい絵文字の使用を可能とする。 - -変更内容と選択される絵文字の対応については厳密とせず、開発者が任意に選択するものとする。 - -type(feat, fix, docs, refactorなど)に基づく、選択例を以下に示す。 - -```txt - ==== Emojis ==== - :ambulance: 🚑致命的なバグ修正(fix) - :bug: 🐛バグ修正(fix) - :+1: 👍機能改善・機能修正(fix) - :cop: 👮セキュリティ関連の修正(fix) - :art: 🎨レイアウト関連の修正(fix) - :green_heart: 💚テストやCIの修正・改善(fix) - :wrench: 🔧設定ファイルの修正(fix) - :building_construction: 🏗️アーキテクチャの変更(fix) - :tada: 🎉大きな機能追加(feat) - :sparkles: ✨部分的な機能追加(feat) - :up: 🆙依存パッケージ等のアップデート(feat) - :memo: 📝ドキュメント修正(docs) - :bulb: 💡ソースコードへのコメント追加や修正(docs) - :lipstick: 💄Lintエラーの修正やコードスタイルの修正(refactor) - :recycle: ♻️リファクタリング(refactor) - :fire: 🔥コードやファイルの削除(refactor) - :rocket: 🚀パフォーマンス改善(refactor) -``` - -## コミットメッセージ例 - -上記のルールに従った、コミットメッセージのサンプルは以下のようなものとなる。 -以下のようなコミットをルールとすることで、変更内容を視覚的に把握しやすくなる利点がある。 - -```txt -feat: カレンダー機能の追加 🎉 -``` - -```txt -fix: メモリリークの修正 🚑 -``` - -```txt -docs: デプロイフローをドキュメント化 📝 -``` - -```txt -refactor: Lintエラーの修正 💄 -``` +--- +sidebarDepth: 4 +title: コミットメッセージ規約 +author: フューチャー株式会社 +--- + +# コミットメッセージ規約 + +Gitのコミットメッセージにの書式についてルール化することで、コミットの目的がわかりやすくなる、履歴からのトラッキングの容易になる利点がある。 + +本規約のコミットメッセージの書式としては、`Conventional Commits`をベースとした規約としている。 + +以下の形式でコミットメッセージを記載することとする。 + +```md +: +``` + +コミットメッセージは +type、subject、gitmojiの最大3つの要素から構成され、それぞれは後述する書式に従うものとする。 +この中でも、type、subjectについては必須とし、ほかの要素についてはプロジェクトの運用にしたがい任意とする。 + +## type + +typeについては必須の要素となり、以下のいずれかを選択するものとする。 + +| type | 説明 | +| ---------- | -------------------------- | +| `feat` | 新機能の追加 | +| `fix` | バグの修正 | +| `docs` | ドキュメンテーションの更新 | +| `refactor` | リファクタリング | + +## subject + +subjectについては必須の要素となり、変更内容を簡潔に記載するものとする。 +issue idについては、PRから参照する運用を想定し、コミットメッセージの必須要素とはしないこととする。 + +## gitmoji + +gitmojiについては任意の要素となり、変更内容を視認しやすい絵文字の使用を可能とする。 + +変更内容と選択される絵文字の対応については厳密とせず、開発者が任意に選択するものとする。 + +type(feat, fix, docs, refactorなど)に基づく、選択例を以下に示す。 + +```txt + ==== Emojis ==== + :ambulance: 🚑致命的なバグ修正(fix) + :bug: 🐛バグ修正(fix) + :+1: 👍機能改善・機能修正(fix) + :cop: 👮セキュリティ関連の修正(fix) + :art: 🎨レイアウト関連の修正(fix) + :green_heart: 💚テストやCIの修正・改善(fix) + :wrench: 🔧設定ファイルの修正(fix) + :building_construction: 🏗️アーキテクチャの変更(fix) + :tada: 🎉大きな機能追加(feat) + :sparkles: ✨部分的な機能追加(feat) + :up: 🆙依存パッケージ等のアップデート(feat) + :memo: 📝ドキュメント修正(docs) + :bulb: 💡ソースコードへのコメント追加や修正(docs) + :lipstick: 💄Lintエラーの修正やコードスタイルの修正(refactor) + :recycle: ♻️リファクタリング(refactor) + :fire: 🔥コードやファイルの削除(refactor) + :rocket: 🚀パフォーマンス改善(refactor) +``` + +## コミットメッセージ例 + +上記のルールに従った、コミットメッセージのサンプルは以下のようなものとなる。 +以下のようなコミットをルールとすることで、変更内容を視覚的に把握しやすくなる利点がある。 + +```txt +feat: カレンダー機能の追加 🎉 +``` + +```txt +fix: メモリリークの修正 🚑 +``` + +```txt +docs: デプロイフローをドキュメント化 📝 +``` + +```txt +refactor: Lintエラーの修正 💄 +``` diff --git a/documents/forGitBranch/git_branch_standards.md b/documents/forGitBranch/git_branch_standards.md index 4d26d5c6..8fbb9d9f 100644 --- a/documents/forGitBranch/git_branch_standards.md +++ b/documents/forGitBranch/git_branch_standards.md @@ -28,7 +28,7 @@ head: ::: warning 有志で作成したドキュメントである -* フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせて工夫された設計開発の方針が存在する。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している +- フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせて工夫された設計開発の方針が存在する。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している ::: @@ -46,12 +46,12 @@ head: | ブランチ名称 | 役割 | ライフサイクル | 派生元ブランチ | 命名規則 | 直プッシュ | | ------------ | ---------------------------- | -------------- | ----------------- | --------------------------------------------------------------------------- | ---------- | -| `main` | プロダクション環境との同期 | 永続的 | - | `main` 固定 | ❌️ | -| `feature` | 特定機能の追加/変更 | 短命 | `main`／`develop` | `feature/${チケット番号}`: 詳細は[featureブランチ](#featureブランチ) を参照 | ✅️※1 | -| `develop` | 開発の大元 | 永続的 | `main` | `develop` 固定。複数必要な場合は `develop2` と連番にする | ❌️ | -| `release` | リリース作業用途 | 短命 | `develop` | `release/${yyyymmdd}` や `release/${リリースバージョン}` など | ❌️ | -| `hotfix` | mainブランチに対する即時修正 | 短命 | `main` | `hotfix/${チケット番号}`: featureブランチに準じる | ✅️ | -| `topic` | 複数人での機能開発用途 | 短命 | `feature` | `topic/${チケット番号}`: featureブランチに準じる | ✅️ | +| `main` | プロダクション環境との同期 | 永続的 | - | `main` 固定 | ❌️ | +| `feature` | 特定機能の追加/変更 | 短命 | `main`／`develop` | `feature/${チケット番号}`: 詳細は[featureブランチ](#featureブランチ) を参照 | ✅️※1 | +| `develop` | 開発の大元 | 永続的 | `main` | `develop` 固定。複数必要な場合は `develop2` と連番にする | ❌️ | +| `release` | リリース作業用途 | 短命 | `develop` | `release/${yyyymmdd}` や `release/${リリースバージョン}` など | ❌️ | +| `hotfix` | mainブランチに対する即時修正 | 短命 | `main` | `hotfix/${チケット番号}`: featureブランチに準じる | ✅️ | +| `topic` | 複数人での機能開発用途 | 短命 | `feature` | `topic/${チケット番号}`: featureブランチに準じる | ✅️ | ※1: topicブランチを利用する場合は、派生させたfeatureブランチへの直プッシュはNGとなる @@ -113,7 +113,7 @@ fixtypo ![hotfix branch](img/branch_strategy_hotfix.drawio.png) -## topicブランチ +## topicブランチ featureブランチで実現する機能を複数人で開発する場合に使用するブランチである。 @@ -169,12 +169,12 @@ featureブランチで実現する機能を複数人で開発する場合に使 概要: -- `develop` の変更にはバグフィックスや軽微なUI向上が含まれ、日次／週次などの頻度でプロダクション環境へリリースされる +- `develop` の変更にはバグフィックスや軽微なUI向上が含まれ、日次／週次などの頻度でプロダクション環境へリリースされる - `develop2` は`develop` ブランチの変更をすべて取り込んだ上で、大型機能の準備を行う必要がある `develop2` 同期の注意点: -- リベースすると `develop2` を元にfeatureブランチを作成して開発している開発者が混乱することになるため、マージコミットをお用いる +- リベースすると `develop2` を元にfeatureブランチを作成して開発している開発者が混乱することになるため、マージコミットをお用いる - 誤操作を避ける目的でcherry-pickは行わない - `devleop2` への同期は、 `develop` -> `main` ブランチに反映されるタイミングで同期を行う（これにより、品質保証済みの変更のみ取り入れることができる９ @@ -496,7 +496,7 @@ git config --global alias.br branch - `pull.rebase`: pull時にリベースする - `rerere.enabled`: コンフリクトの解決を記録しておき、再び同様のコンフリクトが発生した場合に自動適用する - `fetch.prune`: リモートリポジトリで削除されたブランチを削除する -::: + ::: ## git-secrets @@ -520,11 +520,11 @@ git config --global alias.br branch | ------------- | ---------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------ | | General | Require contributors to sign off on web-based commits | チェックなし | 著作権・ライセンス承諾の場合に用いるが、業務アプリ開発では不要 | | | Default branch | develop | | -| Pull Requests | Allow merge commits | ✅️ | main <- developなどのマージ時に必要 | -| | Allow squash merging | ✅️ | develop <- feature はSquash mergeを推奨 | +| Pull Requests | Allow merge commits | ✅️ | main <- developなどのマージ時に必要 | +| | Allow squash merging | ✅️ | develop <- feature はSquash mergeを推奨 | | | Allow rebase merging | - | 利用しないため、チェックを外す | -| | Allow suggest updating pull request branches | ✅️ | Pull Request作成後、ベースブランチが更新された場合、ソースブランチの更新を提案してくれる | -| | Automatically delete head branches | ✅️ | マージ後にfeature branchを削除するため有効にする | +| | Allow suggest updating pull request branches | ✅️ | Pull Request作成後、ベースブランチが更新された場合、ソースブランチの更新を提案してくれる | +| | Automatically delete head branches | ✅️ | マージ後にfeature branchを削除するため有効にする | | Pushes | Limit how many branches and tags can be updated in a single push | 5 | git push origin –mirrorで誤ってリモートブランチを破壊しないようにする。推奨値の5を設定する | ### Access @@ -548,16 +548,16 @@ Branch protection rules にdevelop, mainなど永続的なブランチに保護 | Category | Item | Value | Memo | | ------------------------- | ---------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------- | -| Protect matching branches | Require a pull request before merging | ✅️ | プルリクエストを必須とする | -| | Require approvals | ✅️ | レビューを必須とする | +| Protect matching branches | Require a pull request before merging | ✅️ | プルリクエストを必須とする | +| | Require approvals | ✅️ | レビューを必須とする | | | Required number of approvals before merging | 1 | 最低1名以上の承認を必須とする | | | Dismiss stale pull request approvals when new commits are pushed | - | レビュー承認後のPushで再承認を必要とするかだが、レビュー運用上に支障となることも多く、チェックを外す | -| | Require status checks to pass before merging | ✅️ | CIの成功を条件とする | +| | Require status checks to pass before merging | ✅️ | CIの成功を条件とする | | | Require branches to be up to date before merging | 任意 | CIパイプラインのワークフロー名を指定 | -| | Require conversation resolution before merging | ✅️ | レビューコメントがすべて解決していることを条件とする | -| | Require signed commits | ✅️ | 署名付きコミットを必須化し、セキュアな設定にする | -| | Require linear history | ✅️/- | mainブランチの場合はOFFとするが、developの場合はSquash mergeを求めるため有効にする | -| | Do not allow bypassing the above settings | ✅️ | パイパスを許容しない | +| | Require conversation resolution before merging | ✅️ | レビューコメントがすべて解決していることを条件とする | +| | Require signed commits | ✅️ | 署名付きコミットを必須化し、セキュアな設定にする | +| | Require linear history | ✅️/- | mainブランチの場合はOFFとするが、developの場合はSquash mergeを求めるため有効にする | +| | Do not allow bypassing the above settings | ✅️ | パイパスを許容しない | developブランチに対し「require linear history」を選択することを推奨することで、「Create a merge commit」が選択できないようにする。 @@ -575,16 +575,16 @@ developブランチに対し「require linear history」を選択することを | Category | Item | Value | Memo | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----- | ---- | -| Actions permissions | Allow asset-taskforce, and select non-asset-taskforce, actions and reusable workflows > Allow actions created by GitHub | ✅️ | | -| | Allow asset-taskforce, and select non-asset-taskforce, actions and reusable workflows > Allow actions Marketplace verified creators | ✅️ | | +| Actions permissions | Allow asset-taskforce, and select non-asset-taskforce, actions and reusable workflows > Allow actions created by GitHub | ✅️ | | +| | Allow asset-taskforce, and select non-asset-taskforce, actions and reusable workflows > Allow actions Marketplace verified creators | ✅️ | | #### Code security and analysis | Category | Item | Value | Memo | | ---------- | --------------------------- | ----- | ------------------------------------------ | -| Dependabot | Dependabot alerts | ✅️ | 依存パッケージのアップデートを検知するため | -| | Dependabot security updates | ✅️ | | -| | Dependabot version updates | ✅️ | | +| Dependabot | Dependabot alerts | ✅️ | 依存パッケージのアップデートを検知するため | +| | Dependabot security updates | ✅️ | | +| | Dependabot version updates | ✅️ | | ## GitLab推奨設定 diff --git a/documents/forGitBranch/index.md b/documents/forGitBranch/index.md index 8319109c..459e1c34 100644 --- a/documents/forGitBranch/index.md +++ b/documents/forGitBranch/index.md @@ -3,7 +3,7 @@ sidebarDepth: 4 author: フューチャー株式会社 layout: home hero: - name: Gitブランチフロー規約 + name: Gitブランチフロー規約 tagline: Future Enterprise Standards for Git branch flow actions: - theme: brand diff --git a/documents/forGitBranch/merge_develop_to_feature.md b/documents/forGitBranch/merge_develop_to_feature.md index 0401c09b..d722a4ee 100644 --- a/documents/forGitBranch/merge_develop_to_feature.md +++ b/documents/forGitBranch/merge_develop_to_feature.md @@ -1,49 +1,49 @@ ---- -sidebarDepth: 4 -title: 機能ブランチに開発ブランチの変更を取り込む方法 -author: フューチャー株式会社 ---- - -# 機能ブランチに開発ブランチの変更を取り込む方法 - -機能ブランチに対して開発ブランチの変更を取り込む方法は「マージ」「リベース」2つの方法が考えられる。 - -## 1. マージコミット - -マージとは `get fetch & git merge` コマンド（ = `git pull` コマンド）を使用して、開発ブランチの変更を機能ブランチに取り込む方法を指す。 -マージを行った場合は下記の通り、「マージコミット」が作成される。 - -![マージ](img/merge_strategy_develop_to_feature_merge.drawio.png) - -```bash -# 現在のブランチは 機能（feature/A）ブランチ -$ git branch - develop -* feature/A - -# リモート追跡ブランチの最新化 -$ git fetch - -# 開発（develop）ブランチの変更を機能（feature/A）ブランチにマージ -$ git merge develop -``` - -## 2. リベース - -リベースとは `get fetch & git rebase` コマンド（ = `git pull --rebase` コマンド）を使用して、開発ブランチの変更を機能ブランチに取り込む方法を指す。 -最新の開発ブランチの先頭から新たにコミットを作りなおす動きになるので、マージによる方法と異なり「マージコミット」は作成されない。 - -![リベース](img/merge_strategy_develop_to_feature_rebase.drawio.png) - -```bash -# 現在のブランチは 機能（feature/A）ブランチ -$ git branch - develop -* feature/A - -# リモート追跡ブランチの最新化 -$ git fetch - -# 機能（feature/A）ブランチを開発（develop）ブランチにリベース -$ git rebase develop -``` +--- +sidebarDepth: 4 +title: 機能ブランチに開発ブランチの変更を取り込む方法 +author: フューチャー株式会社 +--- + +# 機能ブランチに開発ブランチの変更を取り込む方法 + +機能ブランチに対して開発ブランチの変更を取り込む方法は「マージ」「リベース」2つの方法が考えられる。 + +## 1. マージコミット + +マージとは `get fetch & git merge` コマンド（ = `git pull` コマンド）を使用して、開発ブランチの変更を機能ブランチに取り込む方法を指す。 +マージを行った場合は下記の通り、「マージコミット」が作成される。 + +![マージ](img/merge_strategy_develop_to_feature_merge.drawio.png) + +```bash +# 現在のブランチは 機能（feature/A）ブランチ +$ git branch + develop +* feature/A + +# リモート追跡ブランチの最新化 +$ git fetch + +# 開発（develop）ブランチの変更を機能（feature/A）ブランチにマージ +$ git merge develop +``` + +## 2. リベース + +リベースとは `get fetch & git rebase` コマンド（ = `git pull --rebase` コマンド）を使用して、開発ブランチの変更を機能ブランチに取り込む方法を指す。 +最新の開発ブランチの先頭から新たにコミットを作りなおす動きになるので、マージによる方法と異なり「マージコミット」は作成されない。 + +![リベース](img/merge_strategy_develop_to_feature_rebase.drawio.png) + +```bash +# 現在のブランチは 機能（feature/A）ブランチ +$ git branch + develop +* feature/A + +# リモート追跡ブランチの最新化 +$ git fetch + +# 機能（feature/A）ブランチを開発（develop）ブランチにリベース +$ git rebase develop +``` diff --git a/documents/forGitBranch/merge_feature_to_develop.md b/documents/forGitBranch/merge_feature_to_develop.md index 309ec502..df896753 100644 --- a/documents/forGitBranch/merge_feature_to_develop.md +++ b/documents/forGitBranch/merge_feature_to_develop.md @@ -1,73 +1,73 @@ ---- -sidebarDepth: 4 -title: 開発ブランチに機能ブランチの変更を取り込む方法 -author: フューチャー株式会社 ---- - -# 開発ブランチに機能ブランチの変更を取り込む方法 - -## GitHubの場合 - -プルリクエストを経由して、開発が完了した機能ブランチをメインの開発ブランチに取り込むためには、GitHub（GitLab）上でプルリクエスト（マージリクエスト）を経由する運用を前提とする。 - -GitHubを利用する場合、開発ブランチに機能ブランチの変更を取り込む方法は3種類ある。 - -1. スカッシュ マージ（Create a merge commit） -2. リベース（Rebase and merge） -3. スカッシュマージ（Squash and merge） - -### 1. マージコミット - -動作としては `git merge --no-ff` コマンドを使用して、機能ブランチの変更を取り込む形になる。 -この方法を選択した場合は、下記のとおり、メインの開発ブランチにマージコミットが作成される。 - -![Merge Commit](img/merge_strategy_feature_to_develop_merge_commit.drawio.png) - -### 2. リベース - -動作としては機能ブランチを最新の開発ブランチにリベースした後に、`git merge --ff` コマンドを使用して、機能ブランチの変更を取り込む形になる。 -この方法を選択した場合は、下記のとおり、メインの開発ブランチにマージコミットは作成されず、履歴が一直線になる。 - -![Rebase and Merge](img/merge_strategy_feature_to_develop_rebase_and_merge.drawio.png) - -### 3. スカッシュマージ - -動作としては `git merge --squash` コマンドを使用して、機能ブランチの変更を取り込む形になる。 -この方法では、機能ブランチで行った変更YとZを1つにまとめたコミットがメインの開発ブランチに作成されます。 - -![Squash and Merge](img/merge_strategy_feature_to_develop_squash_and_merge.drawio.png) - -## GitLabを利用するの手順 - -開発ブランチに機能ブランチの変更を取り込む方法は3種類ある。 -ただし、マージリクエスト上のオプションによってコミット履歴が変わるため、別途記載する。 - -1. Merge commit -2. Merge commit with semi-linear history -3. Fast-forward merge - -### 1. Merge commit - -動作としては、GitHubにおける `Create a merge commit` と同様のマージ方法になる。 -ただし、マージリクエスト上で `Squash commits` を選択してマージした場合、`squash commit` と `merge commit` の2つのコミットが作成されるため注意する。 - -![Merge commit with squash commits](img/merge_strategy_feature_to_develop_squash_and_merge_gitlab.drawio.png) - -```bash -# マージ方法で Merge commit を選択して、マージリクエスト上で Squash commits オプションを選択してマージした場合 -git checkout `git merge-base feature/A develop` -git merge --squash feature/A -SOURCE_SHA=`git rev-parse HEAD` -git checkout develop -git merge --no-ff $SOURCE_SHA -``` - -### 2. Merge commit with semi-linear history - -動作としては、前述の `Merge commit` と同じコマンドを使用して、機能ブランチの変更を取り込む形になる。 -この方法を選択した場合は、ソースブランチがターゲットブランチより古い場合はリベースしないとマージできない。 - -### 3. Fast-forward merge - -動作としては、GitHubにおける `Rebase and merge` と同様のマージ方法になる。 -ただし、マージリクエスト上で `Squash commits` を選択してマージした場合、GitHubにおける `Squash and merge` と同様のマージ方法になる。 +--- +sidebarDepth: 4 +title: 開発ブランチに機能ブランチの変更を取り込む方法 +author: フューチャー株式会社 +--- + +# 開発ブランチに機能ブランチの変更を取り込む方法 + +## GitHubの場合 + +プルリクエストを経由して、開発が完了した機能ブランチをメインの開発ブランチに取り込むためには、GitHub（GitLab）上でプルリクエスト（マージリクエスト）を経由する運用を前提とする。 + +GitHubを利用する場合、開発ブランチに機能ブランチの変更を取り込む方法は3種類ある。 + +1. スカッシュ マージ（Create a merge commit） +2. リベース（Rebase and merge） +3. スカッシュマージ（Squash and merge） + +### 1. マージコミット + +動作としては `git merge --no-ff` コマンドを使用して、機能ブランチの変更を取り込む形になる。 +この方法を選択した場合は、下記のとおり、メインの開発ブランチにマージコミットが作成される。 + +![Merge Commit](img/merge_strategy_feature_to_develop_merge_commit.drawio.png) + +### 2. リベース + +動作としては機能ブランチを最新の開発ブランチにリベースした後に、`git merge --ff` コマンドを使用して、機能ブランチの変更を取り込む形になる。 +この方法を選択した場合は、下記のとおり、メインの開発ブランチにマージコミットは作成されず、履歴が一直線になる。 + +![Rebase and Merge](img/merge_strategy_feature_to_develop_rebase_and_merge.drawio.png) + +### 3. スカッシュマージ + +動作としては `git merge --squash` コマンドを使用して、機能ブランチの変更を取り込む形になる。 +この方法では、機能ブランチで行った変更YとZを1つにまとめたコミットがメインの開発ブランチに作成されます。 + +![Squash and Merge](img/merge_strategy_feature_to_develop_squash_and_merge.drawio.png) + +## GitLabを利用するの手順 + +開発ブランチに機能ブランチの変更を取り込む方法は3種類ある。 +ただし、マージリクエスト上のオプションによってコミット履歴が変わるため、別途記載する。 + +1. Merge commit +2. Merge commit with semi-linear history +3. Fast-forward merge + +### 1. Merge commit + +動作としては、GitHubにおける `Create a merge commit` と同様のマージ方法になる。 +ただし、マージリクエスト上で `Squash commits` を選択してマージした場合、`squash commit` と `merge commit` の2つのコミットが作成されるため注意する。 + +![Merge commit with squash commits](img/merge_strategy_feature_to_develop_squash_and_merge_gitlab.drawio.png) + +```bash +# マージ方法で Merge commit を選択して、マージリクエスト上で Squash commits オプションを選択してマージした場合 +git checkout `git merge-base feature/A develop` +git merge --squash feature/A +SOURCE_SHA=`git rev-parse HEAD` +git checkout develop +git merge --no-ff $SOURCE_SHA +``` + +### 2. Merge commit with semi-linear history + +動作としては、前述の `Merge commit` と同じコマンドを使用して、機能ブランチの変更を取り込む形になる。 +この方法を選択した場合は、ソースブランチがターゲットブランチより古い場合はリベースしないとマージできない。 + +### 3. Fast-forward merge + +動作としては、GitHubにおける `Rebase and merge` と同様のマージ方法になる。 +ただし、マージリクエスト上で `Squash commits` を選択してマージした場合、GitHubにおける `Squash and merge` と同様のマージ方法になる。 diff --git a/documents/forGitBranch/vscode_git_ope.md b/documents/forGitBranch/vscode_git_ope.md index e296a8ed..e4f6b399 100644 --- a/documents/forGitBranch/vscode_git_ope.md +++ b/documents/forGitBranch/vscode_git_ope.md @@ -1,101 +1,101 @@ ---- -sidebarDepth: 4 -title: VSCode上でのGit操作 -author: フューチャー株式会社 ---- - -# VSCode上でのGit操作 - -利用頻度が高いとされるVS CodeでのGit操作を紹介する。 - -VSCode上でのGit操作は、サイドバーの "Source Control" から行うことができる。ほとんど全ての操作はコマンドパレットからも実行可能だが、説明は割愛する。 - -## 推奨する拡張機能 - -GUIでのGit操作にあたり、次の2つの拡張機能をインストールしておくと利便性が高い。業務上はほぼ必須と見て良い。 - -- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) - - Gitに関する様々な機能を提供する拡張機能 - - 詳細：: [VSCodeでGitLensを使う - フューチャー技術ブログ](https://future-architect.github.io/articles/）20240415a/) -- [Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph) - - コミットグラフを表示する拡張機能 - - GitLensにもコミットグラフはありますが、Pro（有料版）限定の提供のため、ここではこちらの拡張機能を使用する - -以降では、これらの拡張機能がインストールされていることを前提に説明を行う。 - -## リポジトリのクローン (`git clone`) - -サイドバー > Explorer か Source Control > Clone Repository ボタンをクリックし、URLを入力すると、リポジトリをクローンできる。 - -![Clone1](img/vscode_git_clone1.png) ![Clone2](img/vscode_git_clone2.png) - -## コミットグラフの表示 - -SOURCE CONTROL パネル > 黒丸のグラフアイコン (View Git Graph (git log)) をクリックすると、コミットグラフを表示できる。 - -白丸のグラフアイコン (Show Commit Graph) はGitLensのコミットグラフだが、冒頭の記述通り、Pro版でのみの提供となる。 - -![Graph1](img/vscode_git_graph1.png) ![Graph2](img/vscode_git_graph2.png) - -## リモートのフェッチ／プル (`git fetch` / `git pull`) - -以下のいずれかの操作を実行すると、リモートリポジトリをフェッチできる。 - -- SOURCE CONTROL パネル > 三点リーダーアイコン (More Actions...) をクリックし、 Fetch を選択 -- コミットグラフ > 雲アイコン (Fetch from Remote(s)) をクリック - -![Fetch1](img/vscode_git_fetch1.png) - -なお、フェッチ後に以下のようなダイアログが表示される場合があるが、 "Yes" を選択すると、自動で定期的にフェッチを行う。 - -![Fetch2](img/vscode_git_fetch2.png) - -[TODO] プルを追記する。 - -## ブランチの作成／チェックアウト (`git branch` / `git checkout`) - -以下のいずれかの操作を実行すると、ブランチを作成できる。 - -- SOURCE CONTROL パネル > 三点リーダーアイコン (More Actions...) をクリックし、Branch > Create Branch... を選択 - - 現在チェックアウトしているブランチから新規ブランチが作成されますが、Create Branch From... を選択すると、作成元のブランチを選択することができる - - 作成したブランチに自動的にチェックアウトする -- コミットグラフ > 作成元コミットの行上で右クリックし、Create Branch... を選択 - - "Check out" にチェックを入れると、作成したブランチにチェックアウトする - -![Branch1](img/vscode_git_branch1.png) ![Branch2](img/vscode_git_branch2.png) - -[TODO] チェックアウトを追記する。 - -## ステージ／コミット／プッシュ (`git add` / `git commit` / `git push`) - -SOURCE CONTROL パネル > 変更ファイルの行 > +アイコン (Stage Changes) をクリックすると、対象ファイルをステージできる。（Changes > +アイコン (Stage All Changes) をクリックすると、すべての変更をステージする） - -![Stage](img/vscode_git_stage.png) - -必要な変更をステージ後、 SOURCE CONTROL パネル内でコミットメッセージを入力し、 Commit ボタンをクリックすると、コミットを作成できる。 - -![Commit](img/vscode_git_commit.png) - -以下のいずれかの操作を実行すると、作成したコミットをリモートリポジトリにプッシュできる。 - -- SOURCE CONTROL パネル > 三点リーダーアイコン (More Actions...) をクリックし、Push を選択 -- BRANCHES パネル > 対象ブランチの行 > 雲アイコン (Publish Branch) をクリック -- コミットグラフ > 対象ブランチの上で右クリックし、Push Branch... を選択 - -![push1](img/vscode_git_push1.png) ![push2](img/vscode_git_push2.png) ![push3](img/vscode_git_push3.png) - -## リバート (`git revert`) - -TODO - -## マージ (`git merge`) - -TODO - -## リベース (`git rebase`) - -TODO - -## スタッシュ (`git stash`) - -TODO +--- +sidebarDepth: 4 +title: VSCode上でのGit操作 +author: フューチャー株式会社 +--- + +# VSCode上でのGit操作 + +利用頻度が高いとされるVS CodeでのGit操作を紹介する。 + +VSCode上でのGit操作は、サイドバーの "Source Control" から行うことができる。ほとんど全ての操作はコマンドパレットからも実行可能だが、説明は割愛する。 + +## 推奨する拡張機能 + +GUIでのGit操作にあたり、次の2つの拡張機能をインストールしておくと利便性が高い。業務上はほぼ必須と見て良い。 + +- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) + - Gitに関する様々な機能を提供する拡張機能 + - 詳細：: [VSCodeでGitLensを使う - フューチャー技術ブログ](https://future-architect.github.io/articles/）20240415a/) +- [Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph) + - コミットグラフを表示する拡張機能 + - GitLensにもコミットグラフはありますが、Pro（有料版）限定の提供のため、ここではこちらの拡張機能を使用する + +以降では、これらの拡張機能がインストールされていることを前提に説明を行う。 + +## リポジトリのクローン (`git clone`) + +サイドバー > Explorer か Source Control > Clone Repository ボタンをクリックし、URLを入力すると、リポジトリをクローンできる。 + +![Clone1](img/vscode_git_clone1.png) ![Clone2](img/vscode_git_clone2.png) + +## コミットグラフの表示 + +SOURCE CONTROL パネル > 黒丸のグラフアイコン (View Git Graph (git log)) をクリックすると、コミットグラフを表示できる。 + +白丸のグラフアイコン (Show Commit Graph) はGitLensのコミットグラフだが、冒頭の記述通り、Pro版でのみの提供となる。 + +![Graph1](img/vscode_git_graph1.png) ![Graph2](img/vscode_git_graph2.png) + +## リモートのフェッチ／プル (`git fetch` / `git pull`) + +以下のいずれかの操作を実行すると、リモートリポジトリをフェッチできる。 + +- SOURCE CONTROL パネル > 三点リーダーアイコン (More Actions...) をクリックし、 Fetch を選択 +- コミットグラフ > 雲アイコン (Fetch from Remote(s)) をクリック + +![Fetch1](img/vscode_git_fetch1.png) + +なお、フェッチ後に以下のようなダイアログが表示される場合があるが、 "Yes" を選択すると、自動で定期的にフェッチを行う。 + +![Fetch2](img/vscode_git_fetch2.png) + +[TODO] プルを追記する。 + +## ブランチの作成／チェックアウト (`git branch` / `git checkout`) + +以下のいずれかの操作を実行すると、ブランチを作成できる。 + +- SOURCE CONTROL パネル > 三点リーダーアイコン (More Actions...) をクリックし、Branch > Create Branch... を選択 + - 現在チェックアウトしているブランチから新規ブランチが作成されますが、Create Branch From... を選択すると、作成元のブランチを選択することができる + - 作成したブランチに自動的にチェックアウトする +- コミットグラフ > 作成元コミットの行上で右クリックし、Create Branch... を選択 + - "Check out" にチェックを入れると、作成したブランチにチェックアウトする + +![Branch1](img/vscode_git_branch1.png) ![Branch2](img/vscode_git_branch2.png) + +[TODO] チェックアウトを追記する。 + +## ステージ／コミット／プッシュ (`git add` / `git commit` / `git push`) + +SOURCE CONTROL パネル > 変更ファイルの行 > +アイコン (Stage Changes) をクリックすると、対象ファイルをステージできる。（Changes > +アイコン (Stage All Changes) をクリックすると、すべての変更をステージする） + +![Stage](img/vscode_git_stage.png) + +必要な変更をステージ後、 SOURCE CONTROL パネル内でコミットメッセージを入力し、 Commit ボタンをクリックすると、コミットを作成できる。 + +![Commit](img/vscode_git_commit.png) + +以下のいずれかの操作を実行すると、作成したコミットをリモートリポジトリにプッシュできる。 + +- SOURCE CONTROL パネル > 三点リーダーアイコン (More Actions...) をクリックし、Push を選択 +- BRANCHES パネル > 対象ブランチの行 > 雲アイコン (Publish Branch) をクリック +- コミットグラフ > 対象ブランチの上で右クリックし、Push Branch... を選択 + +![push1](img/vscode_git_push1.png) ![push2](img/vscode_git_push2.png) ![push3](img/vscode_git_push3.png) + +## リバート (`git revert`) + +TODO + +## マージ (`git merge`) + +TODO + +## リベース (`git rebase`) + +TODO + +## スタッシュ (`git stash`) + +TODO diff --git a/documents/forJava/index.md b/documents/forJava/index.md index b1ed21dd..2fa2a0d7 100644 --- a/documents/forJava/index.md +++ b/documents/forJava/index.md @@ -3,7 +3,7 @@ sidebarDepth: 4 author: フューチャー株式会社 layout: home hero: - name: Javaコーディング規約 + name: Javaコーディング規約 tagline: Future Enterprise Coding Standards for Java image: src: /images/JBee.png diff --git "a/documents/forMarkdown/IF\345\256\232\347\276\251\346\233\270.md" "b/documents/forMarkdown/IF\345\256\232\347\276\251\346\233\270.md" index 0acbd098..0f56f154 100644 --- "a/documents/forMarkdown/IF\345\256\232\347\276\251\346\233\270.md" +++ "b/documents/forMarkdown/IF\345\256\232\347\276\251\346\233\270.md" @@ -12,21 +12,21 @@ ### Input -| Item | Value | -| ---------------- | ------------------------------------------------ | -| 連携 S3 バケット | `${env}-example-import` | +| Item | Value | +| ---------------- | ---------------------------------------------- | +| 連携 S3 バケット | `${env}-example-import` | | プレフィックス | `activate/year=${yyyy}/month=${MM}/day=${dd}/` | -| ファイル名 | `${yyyy}-${mm}-${dd}-${hh}-${MM}-${SS}.csv` | -| 保持期限 | 3 年 | +| ファイル名 | `${yyyy}-${mm}-${dd}-${hh}-${MM}-${SS}.csv` | +| 保持期限 | 3 年 | ### Output -| Item | Value | -| ---------------- | ------------------------------------------------ | -| 連携 S3 バケット | `${env}-example-import` | +| Item | Value | +| ---------------- | ---------------------------------------------- | +| 連携 S3 バケット | `${env}-example-import` | | プレフィックス | `activate/year=${yyyy}/month=${MM}/day=${dd}/` | -| ファイル名 | `${yyyy}-${mm}-${dd}-${hh}-${MM}-${SS}.csv` | -| 保持期限 | 3 年 | +| ファイル名 | `${yyyy}-${mm}-${dd}-${hh}-${MM}-${SS}.csv` | +| 保持期限 | 3 年 | ## 連携元定義 @@ -36,7 +36,7 @@ | | 連携タイミング（随時/定時） | 定時 | | | | 頻度 | 1 回/日 | | | | 起動時間 | **16:00** | | -| | 処理完了期限 | **16:00** | | +| | 処理完了期限 | **16:00** | | | | 未着チェック（なし/WARN/ERROR） | WARN | | | | 全件/差分 | 差分 | | | | 0 件時連携 | あり | | @@ -76,7 +76,7 @@ company_cd,device_cd,activation_date | | 連携タイミング（随時/定時） | 定時 | | | | 頻度 | 1 回/日 | | | | 起動時間 | **16:00** | | -| | 処理完了期限 | **16:00** | | +| | 処理完了期限 | **16:00** | | | | 未着チェック（なし/WARN/ERROR） | WARN | | | | 全件/差分 | 差分 | | | | 0 件時連携 | あり | | @@ -156,6 +156,6 @@ end ## エラー処理 -| Pattern | Description | recovery | -|-----------|-----------------------|---------------------------------------| +| Pattern | Description | recovery | +| ------------------ | ------------------------------------------ | -------------------------------------- | | フォーマットエラー | 連携元から提供されているデータ形式が想定外 | 連携元またはIFの処理内容の修正と再実行 | diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM01/index.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM01/index.md" index 7340e793..6d0ec71e 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM01/index.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM01/index.md" @@ -38,7 +38,7 @@ 画面表示制御: - HTTPステータスが400系 - - 「IDまたはパスワードが異なります」を表示 + - 「IDまたはパスワードが異なります」を表示 - HTTPステータスが500系 - メッセージID（MSG_BIZ_111）表示 - HTTPステータスが200 diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/index.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/index.md" index 0447d0ef..187b5776 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/index.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/index.md" @@ -1,6 +1,6 @@ # 画面 -* [Figma URL](https://www.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=0-1&t=WUJH1mSc5HgzhHcH-1) +- [Figma URL](https://www.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=0-1&t=WUJH1mSc5HgzhHcH-1) ## 標準画面 diff --git a/documents/forMarkdown/future_muscle_partner/docs/02_WebAPI/openapi.yaml b/documents/forMarkdown/future_muscle_partner/docs/02_WebAPI/openapi.yaml index 5ed81f80..b6b4be05 100644 --- a/documents/forMarkdown/future_muscle_partner/docs/02_WebAPI/openapi.yaml +++ b/documents/forMarkdown/future_muscle_partner/docs/02_WebAPI/openapi.yaml @@ -33,16 +33,16 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/LoginRequest' + $ref: "#/components/schemas/LoginRequest" responses: - '200': + "200": description: ログインに成功しました。 - '400': - $ref: '#/components/responses/BadRequest' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /logout: post: tags: @@ -51,20 +51,20 @@ paths: operationId: logout security: [] responses: - '200': + "200": description: ログアウトに成功しました。 - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '403': - $ref: '#/components/responses/Forbidden' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /signup: post: tags: @@ -77,16 +77,16 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/SignupRequest' + $ref: "#/components/schemas/SignupRequest" responses: - '200': + "200": description: 会員登録に成功しました。 - '400': - $ref: '#/components/responses/BadRequest' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /account: delete: tags: @@ -94,16 +94,16 @@ paths: summary: API004 会員退会 operationId: deleteAccount responses: - '200': + "200": description: 会員退会に成功しました。 - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /profile/{trainee_id}: get: tags: @@ -111,18 +111,18 @@ paths: summary: API005 プロフィール表示 operationId: getUserProfile responses: - '200': + "200": description: プロフィールの取得に成功しました。 content: application/json: schema: - $ref: '#/components/schemas/Profile' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + $ref: "#/components/schemas/Profile" + "401": + $ref: "#/components/responses/Unauthorized" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" put: tags: - profile @@ -140,16 +140,16 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ProfileRequest' + $ref: "#/components/schemas/ProfileRequest" responses: - '200': + "200": description: プロフィールの更新に成功しました。 - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "401": + $ref: "#/components/responses/Unauthorized" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /trainers: get: tags: @@ -194,18 +194,18 @@ paths: format: integer enum: [1, 2, 3] responses: - '200': + "200": description: トレーナーの検索結果を取得しました。 content: application/json: schema: - $ref: '#/components/schemas/Trainers' - '400': - $ref: '#/components/responses/BadRequest' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + $ref: "#/components/schemas/Trainers" + "400": + $ref: "#/components/responses/BadRequest" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /trainers/{trainer_id}/menus: get: tags: @@ -221,20 +221,20 @@ paths: schema: type: string responses: - '200': + "200": description: トレーニングメニューを取得しました。 content: application/json: schema: - $ref: '#/components/schemas/TrainingMenus' - '400': - $ref: '#/components/responses/BadRequest' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + $ref: "#/components/schemas/TrainingMenus" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /trainers/{trainer_id}/profile: get: @@ -251,20 +251,20 @@ paths: schema: type: string responses: - '200': + "200": description: トレーナープロフィールを取得しました。 content: application/json: schema: - $ref: '#/components/schemas/Trainer' - '400': - $ref: '#/components/responses/BadRequest' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + $ref: "#/components/schemas/Trainer" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /trainers/{trainer_id}/reviews: get: tags: @@ -280,20 +280,20 @@ paths: schema: type: string responses: - '200': + "200": description: トレーナーの口コミを取得しました。 content: application/json: schema: - $ref: '#/components/schemas/Reviews' - '400': - $ref: '#/components/responses/BadRequest' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + $ref: "#/components/schemas/Reviews" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /trainers/{trainer_id}/schedule: get: tags: @@ -309,20 +309,20 @@ paths: schema: type: string responses: - '200': + "200": description: トレーナーのスケジュールを取得しました。 content: application/json: schema: - $ref: '#/components/schemas/TrainerSchedules' - '400': - $ref: '#/components/responses/BadRequest' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + $ref: "#/components/schemas/TrainerSchedules" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /bookings: post: tags: @@ -334,22 +334,22 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/BookingRequest' + $ref: "#/components/schemas/BookingRequest" responses: - '200': + "200": description: 予約が仮登録されました。 - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '409': - $ref: '#/components/responses/Conflict' - '422': - $ref: '#/components/responses/UnprocessableEntity' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "409": + $ref: "#/components/responses/Conflict" + "422": + $ref: "#/components/responses/UnprocessableEntity" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /bookings/{trainee_id}: get: tags: @@ -374,18 +374,18 @@ paths: schema: type: string responses: - '200': + "200": description: ユーザーの予約情報を取得しました。 content: application/json: schema: - $ref: '#/components/schemas/Bookings' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + $ref: "#/components/schemas/Bookings" + "401": + $ref: "#/components/responses/Unauthorized" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /bookings/{booking_id}: delete: tags: @@ -400,18 +400,18 @@ paths: schema: type: string responses: - '200': + "200": description: 予約が削除されました。 - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /bookings/{booking_id}/confirm: post: tags: @@ -430,22 +430,22 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/BookingConfirmationRequest' + $ref: "#/components/schemas/BookingConfirmationRequest" responses: - '200': + "200": description: 予約が本登録されました。 - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '409': - $ref: '#/components/responses/Conflict' - '422': - $ref: '#/components/responses/UnprocessableEntity' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "409": + $ref: "#/components/responses/Conflict" + "422": + $ref: "#/components/responses/UnprocessableEntity" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /booking/{booking_id}/status: put: tags: @@ -464,24 +464,24 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TrainingStatusUpdateRequest' + $ref: "#/components/schemas/TrainingStatusUpdateRequest" responses: - '200': + "200": description: ステータスが更新されました。 - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '404': - $ref: '#/components/responses/NotFound' - '409': - $ref: '#/components/responses/Conflict' - '422': - $ref: '#/components/responses/UnprocessableEntity' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + "409": + $ref: "#/components/responses/Conflict" + "422": + $ref: "#/components/responses/UnprocessableEntity" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /payment: post: tags: @@ -493,22 +493,22 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/PaymentRequest' + $ref: "#/components/schemas/PaymentRequest" responses: - '200': + "200": description: 決済が完了しました。 - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '409': - $ref: '#/components/responses/Conflict' - '422': - $ref: '#/components/responses/UnprocessableEntity' - '500': - $ref: '#/components/responses/InternalServer' - '503': - $ref: '#/components/responses/ServiceUnavailable' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "409": + $ref: "#/components/responses/Conflict" + "422": + $ref: "#/components/responses/UnprocessableEntity" + "500": + $ref: "#/components/responses/InternalServer" + "503": + $ref: "#/components/responses/ServiceUnavailable" /reviews: post: tags: @@ -520,9 +520,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ReviewRequest' + $ref: "#/components/schemas/ReviewRequest" responses: - '200': + "200": description: 口コミ登録成功 /reviews/{review_id}: put: @@ -542,9 +542,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ReviewUpdateRequest' + $ref: "#/components/schemas/ReviewUpdateRequest" responses: - '200': + "200": description: 口コミ修正成功 delete: tags: @@ -559,7 +559,7 @@ paths: schema: type: string responses: - '200': + "200": description: 口コミ削除成功 /trainer: post: @@ -572,9 +572,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Trainer' + $ref: "#/components/schemas/Trainer" responses: - '200': + "200": description: トレーナー登録成功 put: tags: @@ -586,9 +586,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Trainer' + $ref: "#/components/schemas/Trainer" responses: - '200': + "200": description: トレーナー属性更新成功 /training-menus: post: @@ -601,9 +601,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TrainingMenu' + $ref: "#/components/schemas/TrainingMenu" responses: - '200': + "200": description: トレーニングメニュー登録成功 /training-menus/{menu_id}: put: @@ -623,9 +623,9 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TrainingMenu' + $ref: "#/components/schemas/TrainingMenu" responses: - '200': + "200": description: トレーニングメニュー更新成功 delete: tags: @@ -640,7 +640,7 @@ paths: schema: type: integer responses: - '200': + "200": description: トレーニングメニュー削除成功 components: @@ -803,7 +803,7 @@ components: bokkings: type: array items: - $ref: '#/components/schemas/Booking' + $ref: "#/components/schemas/Booking" Booking: type: object properties: @@ -856,7 +856,7 @@ components: items: type: array items: - $ref: '#/components/schemas/Trainer' + $ref: "#/components/schemas/Trainer" Trainer: type: object properties: @@ -903,7 +903,7 @@ components: items: type: array items: - $ref: '#/components/schemas/TrainerSchedule' + $ref: "#/components/schemas/TrainerSchedule" TrainerSchedule: type: object properties: @@ -1259,7 +1259,7 @@ components: items: type: array items: - $ref: '#/components/schemas/TrainingMenu' + $ref: "#/components/schemas/TrainingMenu" TrainingMenu: type: object properties: @@ -1292,7 +1292,7 @@ components: items: type: array items: - $ref: '#/components/schemas/Review' + $ref: "#/components/schemas/Review" Review: type: object properties: @@ -1370,4 +1370,4 @@ components: type: http scheme: bearer bearerFormat: JWT - description: 'Bearer トークン認証' + description: "Bearer トークン認証" diff --git a/documents/forMarkdown/future_muscle_partner/docs/README.md b/documents/forMarkdown/future_muscle_partner/docs/README.md index 08b1a375..3bb2564e 100644 --- a/documents/forMarkdown/future_muscle_partner/docs/README.md +++ b/documents/forMarkdown/future_muscle_partner/docs/README.md @@ -15,9 +15,9 @@ docs ## 設計書 -- [01_画面](./01_画面/index.md) +- [01\_画面](./01_画面/index.md) - [02_WebAPI](./02_WebAPI/index.md) -- [03_データ](./03_データ/index.md) +- [03\_データ](./03_データ/index.md) ## コード体系 diff --git a/documents/forMarkdown/index.md b/documents/forMarkdown/index.md index c943c755..6ed98bac 100644 --- a/documents/forMarkdown/index.md +++ b/documents/forMarkdown/index.md @@ -3,7 +3,7 @@ sidebarDepth: 4 author: フューチャー株式会社 layout: home hero: - name: 'Markdown設計ドキュメント規約' + name: 'Markdown設計ドキュメント規約' tagline: Future Enterprise Markdown Design Document Standards --- diff --git "a/documents/forMarkdown/\343\203\241\343\203\203\343\202\273\343\203\274\343\202\270\350\250\255\350\250\210\346\233\270.md" "b/documents/forMarkdown/\343\203\241\343\203\203\343\202\273\343\203\274\343\202\270\350\250\255\350\250\210\346\233\270.md" index 30175def..30dbb3ef 100644 --- "a/documents/forMarkdown/\343\203\241\343\203\203\343\202\273\343\203\274\343\202\270\350\250\255\350\250\210\346\233\270.md" +++ "b/documents/forMarkdown/\343\203\241\343\203\203\343\202\273\343\203\274\343\202\270\350\250\255\350\250\210\346\233\270.md" @@ -9,7 +9,7 @@ | 識別子 | レベル | ステータス | メッセージ | コメント | | ------ | ------ | ---------- | ------------------------------------------ | ---------------------------- | -| 10001 | E | 400 | ユーザー名またはパスワードが間違っています | ログイン画面で発生 | +| 10001 | E | 400 | ユーザー名またはパスワードが間違っています | ログイン画面で発生 | | 10002 | W | | 文字数オーバーです | ログイン画面で発生 | -| 10003 | E | 500 | {domain}は無効なユーザードメインです | ユーザーの所属が異なっている | -| 10004 | F | 500 | EntraIDに接続できません | ログインのバックエンドで発生 | +| 10003 | E | 500 | {domain}は無効なユーザードメインです | ユーザーの所属が異なっている | +| 10004 | F | 500 | EntraIDに接続できません | ログインのバックエンドで発生 | diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md index b2dbfdad..3297b17d 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md @@ -26,7 +26,7 @@ Web API 自体の設計については範囲外としますが、[API 設計標 ::: warning 有志で作成したドキュメントである -* フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している +- フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している ::: @@ -133,14 +133,14 @@ definitions: info オブジェクトには Web API に関するメタデータを記載する。 `title`, `description`, `version` を必須項目とする。 -| フィールド名 | 必須 | 記載内容 | -| -------------- | :---: | -------------------------------- | -| title | ○ | Web API の総称 | -| description | ○ | Web API の簡単な説明 | -| version | ○ | OpenAPI ドキュメントのバージョン | -| termsOfService | | 利用規約の URL | -| contact | | 連絡先情報 | -| license | | ライセンス情報 | +| フィールド名 | 必須 | 記載内容 | +| -------------- | :--: | -------------------------------- | +| title | ○ | Web API の総称 | +| description | ○ | Web API の簡単な説明 | +| version | ○ | OpenAPI ドキュメントのバージョン | +| termsOfService | | 利用規約の URL | +| contact | | 連絡先情報 | +| license | | ライセンス情報 | ### title diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index 70147ed3..3b9c6a90 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -24,7 +24,7 @@ Web API の設計自体はこの規約の範囲外であるが、[API 設計標 ::: warning 有志で作成したドキュメントである -* フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している +- フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせた開発手法が採用されている。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している ::: @@ -40,16 +40,16 @@ OpenAPI ドキュメントを構成する要素はオブジェクトと呼ばれ 各オブジェクトの詳細については[公式ドキュメント](https://spec.openapis.org/oas/v3.0.3#openapi-object)を参照されたい。 -| フィールド名 | 必須 | 説明 | -| ------------ | :---: | ----------------------------------------------------------- | -| openapi | ○ | OpenAPI ドキュメントが使用する OpenAPI 仕様のバージョン番号 | -| info | ○ | API に関するメタデータ | -| servers | | API サーバへの接続情報 | -| paths | ○ | API の利用可能なパスと操作方法 | -| components | | 複数の API における共通の定義 | -| security | | API 全体で利用可能なセキュリティ（認証）機構 | -| tags | | 各種 API をグルーピングするためのタグ | -| externalDocs | | 追加の外部ドキュメント | +| フィールド名 | 必須 | 説明 | +| ------------ | :--: | ----------------------------------------------------------- | +| openapi | ○ | OpenAPI ドキュメントが使用する OpenAPI 仕様のバージョン番号 | +| info | ○ | API に関するメタデータ | +| servers | | API サーバへの接続情報 | +| paths | ○ | API の利用可能なパスと操作方法 | +| components | | 複数の API における共通の定義 | +| security | | API 全体で利用可能なセキュリティ（認証）機構 | +| tags | | 各種 API をグルーピングするためのタグ | +| externalDocs | | 追加の外部ドキュメント | # 要素規約 @@ -79,14 +79,14 @@ openapi: 3.0 `title`, `description`, `version` を必須項目とする。 -| フィールド名 | 必須 | 記載内容 | -| -------------- | :---: | -------------------------------- | -| title | ○ | Web API の総称 | -| description | ○ | Web API の簡単な説明 | -| version | ○ | OpenAPI ドキュメントのバージョン | -| termsOfService | | 利用規約の URL | -| contact | | 連絡先情報 | -| license | | ライセンス情報 | +| フィールド名 | 必須 | 記載内容 | +| -------------- | :--: | -------------------------------- | +| title | ○ | Web API の総称 | +| description | ○ | Web API の簡単な説明 | +| version | ○ | OpenAPI ドキュメントのバージョン | +| termsOfService | | 利用規約の URL | +| contact | | 連絡先情報 | +| license | | ライセンス情報 | ### info > title @@ -112,6 +112,7 @@ Web API が提供する機能の概要・想定する利用者やユースケー アプリケーションのバージョン（git tag やリリースで管理するようなバージョン）とは別である。 - `major.minor` 形式を推奨する + - `0.1` 固定で開発を進め、サービスのリリース時に `1.0` とし、その後の項目やオプション、パスの追加ごとにマイナーバージョンをインクリメントしていく 良い例： @@ -135,7 +136,7 @@ Web API が提供する機能の概要・想定する利用者やユースケー Web API を提供するサーバの情報を記載する。 - `url`, `description` を必須項目とする -- ステージ（local, develop, staging など）が複数ある場合は各ステージ分の情報を記載する。 +- ステージ（local, develop, staging など）が複数ある場合は各ステージ分の情報を記載する。 - SSKDs 向けの Web API 開発においては本番環境の URL を不用意に公開したくないケースが多く、記載は避けるべきである 良い例： @@ -195,8 +196,7 @@ API の利用可能なエンドポイントと操作方法を記載する。 ```yaml paths: /product-owners: - get: - ... + get: ... ``` 悪い例： @@ -204,8 +204,7 @@ API の利用可能なエンドポイントと操作方法を記載する。 ```yaml paths: /productOwners: - get: - ... + get: ... ``` - HTTP メソッドは `GET`, `POST`, `PUT`, `PATCH`, `DELETE` の順に定義する @@ -230,20 +229,20 @@ API の利用可能なエンドポイントと操作方法を記載する。 - HTTP メソッドの配下に定義されるオペレーションオブジェクトは、下記の項目を必須項目とする -| フィールド名 | 必須 | 記載内容 | -| ------------ | :---: | ---------------------------------------- | -| tags | ○ | API の論理的なグループ | -| summary | ○ | API の操作概要 | -| description | ○ | API の振る舞いの詳細や注意点 | -| externalDocs | | API に関する追加の文書 | -| operationId | ○ | API の利用可能なエンドポイントと操作方法 | -| parameters | | API のリクエストパラメータ | -| requestBody | | API のリクエストボディ | -| responses | ○ | API のレスポンス | -| callbacks | | | -| deprecated | | API が非推奨であることの宣言 | -| security | | API のセキュリティ機構 | -| servers | | API に対応する代替サーバ | +| フィールド名 | 必須 | 記載内容 | +| ------------ | :--: | ---------------------------------------- | +| tags | ○ | API の論理的なグループ | +| summary | ○ | API の操作概要 | +| description | ○ | API の振る舞いの詳細や注意点 | +| externalDocs | | API に関する追加の文書 | +| operationId | ○ | API の利用可能なエンドポイントと操作方法 | +| parameters | | API のリクエストパラメータ | +| requestBody | | API のリクエストボディ | +| responses | ○ | API のレスポンス | +| callbacks | | | +| deprecated | | API が非推奨であることの宣言 | +| security | | API のセキュリティ機構 | +| servers | | API に対応する代替サーバ | ### paths > {path} > {method} > tags @@ -315,7 +314,7 @@ API の操作概要を記載する。 paths: /users: get: - summary: API-001 ユーザ一覧取得 + summary: API-001 ユーザ一覧取得 ``` ### paths > {path} > {method} > description @@ -324,20 +323,21 @@ API の振る舞いの詳細や注意点を記載する。 別途参照させるべき設計書があるのであれば、設計書へのリンクを記載しても良い。 - 良い例： +良い例： - ```yaml - paths: - /users: - get: - description: [API詳細設計書（API-001）](https://example.com/API-001.md) - ``` +```yaml +paths: + /users: + get: + description: [API詳細設計書（API-001）](https://example.com/API-001.md) +``` ### paths > {path} > {method} > operationId API を識別するための一意な文字列を記載する。 - HTTP メソッドと URL パスの組み合わせをキャメルケースで表現する + - キャメルケースの書式は、[OpenAPI 3.0ガイドのPaths and Operations](https://swagger.io/docs/specification/paths-and-operations/#:~:text=role%3Dvalue-,operationId,-operationId%20is%20an)でも利用されているため、一般的である 良い例： @@ -533,11 +533,10 @@ API のレスポンスを記載する。 /products: post: responses: - '200': + "200": description: 200 OK content: - application/json: - ... + application/json: ... ``` 悪い例： @@ -547,17 +546,16 @@ API のレスポンスを記載する。 /products: post: responses: - '200': + "200": # コンポーネント化したレスポンスオブジェクトを参照 - $ref: '#/components/responses/RespPostProductsBody' + $ref: "#/components/responses/RespPostProductsBody" components: responses: RespPostProductsBody: description: 200 OK content: - application/json: - ... + application/json: ... ``` - 異常系（`4xx`, `5xx`）のレスポンスは個別に定義するのではなく、事前に `components` オブジェクトとして定義を行い `$ref` で参照する @@ -569,17 +567,16 @@ API のレスポンスを記載する。 /products: post: responses: - '400': + "400": # コンポーネント化したレスポンスオブジェクトを参照 - $ref: '#/components/responses/BadRequest' + $ref: "#/components/responses/BadRequest" components: responses: BadRequest: description: 400 Bad Request content: - application/json: - ... + application/json: ... ``` 悪い例： @@ -589,12 +586,11 @@ API のレスポンスを記載する。 /products: post: responses: - '400': + "400": # レスポンスオブジェクトを個別に定義 description: 400 Bad Request content: - application/json: - ... + application/json: ... ``` ### paths > {path} > {method} > security @@ -654,16 +650,14 @@ components: # 共通で使用するリソースを表すオブジェクト Product: type: object - properties: - ... + properties: ... User: type: object properties: # 共通で使用するエラーを表すオブジェクト ProblemDetailError: type: object - properties: - ... + properties: ... ``` ### components > responses @@ -785,7 +779,7 @@ paths: post: /products: parameters: - - $ref: '#/components/parameters/HeaderContentType' + - $ref: "#/components/parameters/HeaderContentType" components: parameters: @@ -810,7 +804,7 @@ paths: get: /products: parameters: - - $ref: '#/components/parameters/CookieCSRFToken' + - $ref: "#/components/parameters/CookieCSRFToken" components: parameters: @@ -843,7 +837,7 @@ paths: "200": headers: XCacheInfo: - $ref: '#/components/headers/XCacheInfo' + $ref: "#/components/headers/XCacheInfo" components: headers: @@ -867,7 +861,7 @@ components: type: http scheme: bearer bearerFormat: JWT - description: 'Bearer トークン認証' + description: "Bearer トークン認証" ``` ### components > links @@ -1199,6 +1193,7 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 2. テストツールとして [stoplightio/prism](https://github.com/stoplightio/prism)を使用する場合、テストケースごとにデータファイルを作成して、`examples` にファイルパスを指定する。 注意点: + - OpenAPI 仕様上、`$ref` は[利用できる箇所が限定されている](https://swagger.io/docs/specification/using-ref/#allowed-places)ことに注意する - 例えば[Path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#path-item-object)は `$ref` が利用可能だが、[Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object)（HTTPメソッドの粒度）では利用不可である @@ -1234,7 +1229,7 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 type: http scheme: bearer bearerFormat: JWT - description: 'Authenthicaiton with bearer token' + description: "Authenthicaiton with bearer token" ``` ```sh @@ -1286,33 +1281,33 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 content: application/json: schema: - type: object - properties: - pet_detail: - type: object - properties: - breeder: - type: string - date_of_birth: - type: string - format: date - pedigree: - type: object - properties: - registration_no: - type: integer - format: int64 - date_of_registration: - type: string - format: date - pedigree_image: - type: string - required: - - registration_no - - date_of_registration - - pedigree_image - required: - - pet_detail + type: object + properties: + pet_detail: + type: object + properties: + breeder: + type: string + date_of_birth: + type: string + format: date + pedigree: + type: object + properties: + registration_no: + type: integer + format: int64 + date_of_registration: + type: string + format: date + pedigree_image: + type: string + required: + - registration_no + - date_of_registration + - pedigree_image + required: + - pet_detail examples: TestCase003: $ref: "../examples/pets_pet_id_get/test_case_003.yaml" @@ -1326,12 +1321,11 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 - OpenAPI の使用用途により、分割ファイルを1つのファイルにまとめる必要がある場合には、例えば[Redocly CLI](https://redocly.com/redocly-cli)を使用して以下コマンドを実行する - まとめたファイルは、以下のようになる（例: openapi.gen.yaml）。 - + ```bash redocly bundle openapi.yaml --output openapi.gen.yaml ``` -
openapi.gen.yamlを見る @@ -1366,7 +1360,7 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 format: int32 required: false responses: - '200': + "200": description: A paged array of pets headers: x-next: @@ -1416,13 +1410,13 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 - sex examples: TestCase001: - $ref: '#/components/examples/test_case_001' + $ref: "#/components/examples/test_case_001" TestCase002: - $ref: '#/components/examples/test_case_002' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' + $ref: "#/components/examples/test_case_002" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" post: summary: Register a pet description: Reginster basic information of new pet. @@ -1472,10 +1466,10 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 - pet examples: TestCase004: - $ref: '#/components/examples/test_case_004' + $ref: "#/components/examples/test_case_004" required: true responses: - '200': + "200": description: OK content: application/json: @@ -1512,10 +1506,10 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 - category - age - sex - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" /pets/{pet_id}: get: summary: Get details of a pet @@ -1531,7 +1525,7 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 type: string required: true responses: - '200': + "200": description: Expected response to a valid request content: application/json: @@ -1565,11 +1559,11 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 - pet_detail examples: TestCase003: - $ref: '#/components/examples/test_case_003' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' + $ref: "#/components/examples/test_case_003" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" components: securitySchemes: Bearer: @@ -1631,10 +1625,10 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 value: pet_detail: breeder: BreederName - date_of_birth: '2023-10-31' + date_of_birth: "2023-10-31" pedigree: registration_no: 11111111 - date_of_registration: '2023-10-31' + date_of_registration: "2023-10-31" pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg schemas: ProblemDetailError: @@ -1654,13 +1648,13 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 content: application/json: schema: - $ref: '#/components/schemas/ProblemDetailError' + $ref: "#/components/schemas/ProblemDetailError" InternalServerError: description: Internal Server Error content: application/json: schema: - $ref: '#/components/schemas/ProblemDetailError' + $ref: "#/components/schemas/ProblemDetailError" ```
diff --git a/documents/forOpenAPISpecification/index.md b/documents/forOpenAPISpecification/index.md index 1e2739ee..b2ed8a53 100644 --- a/documents/forOpenAPISpecification/index.md +++ b/documents/forOpenAPISpecification/index.md @@ -3,7 +3,7 @@ sidebarDepth: 4 author: フューチャー株式会社 layout: home hero: - name: 'OpenAPI Specification規約' + name: 'OpenAPI Specification規約' tagline: Future Enterprise Naming Convention Standards for OpenAPI Specification actions: - theme: brand diff --git a/documents/forOpenAPISpecification/sample_divided/common/responses.yaml b/documents/forOpenAPISpecification/sample_divided/common/responses.yaml index 3ea23551..bc34f60d 100644 --- a/documents/forOpenAPISpecification/sample_divided/common/responses.yaml +++ b/documents/forOpenAPISpecification/sample_divided/common/responses.yaml @@ -1,26 +1,26 @@ -components: - schemas: - ProblemDetailError: - type: object - properties: - code: - type: integer - format: int32 - message: - type: string - required: - - code - - message - responses: - NotFound: - description: Not Found - content: - application/json: - schema: - $ref: "#/components/schemas/ProblemDetailError" - InternalServerError: - description: Internal Server Error - content: - application/json: - schema: - $ref: "#/components/schemas/ProblemDetailError" +components: + schemas: + ProblemDetailError: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + required: + - code + - message + responses: + NotFound: + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/ProblemDetailError" + InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + $ref: "#/components/schemas/ProblemDetailError" diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_001.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_001.yaml index 378e2849..22910c06 100644 --- a/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_001.yaml +++ b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_001.yaml @@ -1,34 +1,34 @@ -value: - pets: - - id: 10001 - name: ToyPoodle - category: dog - sub_category: ToyPoodle - age: 1 - sex: male - note: friendly - tag: dog10001 - - id: 10002 - name: Chihuahua - category: dog - sub_category: Chihuahua - age: 1 - sex: female - note: friendly - tag: dog10002 - - id: 10003 - name: Shiba - category: dog - sub_category: Shiba - age: 1 - sex: male - note: friendly - tag: dog10003 - - id: 10004 - name: MiniatureDachshund - category: dog - sub_category: MiniatureDachshund - age: 1 - sex: female - note: friendly - tag: dog10004 +value: + pets: + - id: 10001 + name: ToyPoodle + category: dog + sub_category: ToyPoodle + age: 1 + sex: male + note: friendly + tag: dog10001 + - id: 10002 + name: Chihuahua + category: dog + sub_category: Chihuahua + age: 1 + sex: female + note: friendly + tag: dog10002 + - id: 10003 + name: Shiba + category: dog + sub_category: Shiba + age: 1 + sex: male + note: friendly + tag: dog10003 + - id: 10004 + name: MiniatureDachshund + category: dog + sub_category: MiniatureDachshund + age: 1 + sex: female + note: friendly + tag: dog10004 diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_002.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_002.yaml index 8b00e7ef..e76ec010 100644 --- a/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_002.yaml +++ b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_002.yaml @@ -1,2 +1,2 @@ -value: - pets: [] +value: + pets: [] diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/test_case_003.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/test_case_003.yaml index 04dc7697..ccdc896c 100644 --- a/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/test_case_003.yaml +++ b/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/test_case_003.yaml @@ -1,8 +1,8 @@ -value: - pet_detail: - breeder: BreederName - date_of_birth: '2023-10-31' - pedigree: - registration_no: 11111111 - date_of_registration: '2023-10-31' - pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg +value: + pet_detail: + breeder: BreederName + date_of_birth: "2023-10-31" + pedigree: + registration_no: 11111111 + date_of_registration: "2023-10-31" + pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg diff --git a/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml b/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml index b25173c9..1b9b9e03 100644 --- a/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml +++ b/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml @@ -27,7 +27,7 @@ paths: format: int32 required: false responses: - '200': + "200": description: A paged array of pets headers: x-next: @@ -77,13 +77,13 @@ paths: - sex examples: TestCase001: - $ref: '#/components/examples/test_case_001' + $ref: "#/components/examples/test_case_001" TestCase002: - $ref: '#/components/examples/test_case_002' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' + $ref: "#/components/examples/test_case_002" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" post: summary: Register a pet description: Reginster basic information of new pet. @@ -133,10 +133,10 @@ paths: - pet examples: TestCase004: - $ref: '#/components/examples/test_case_004' + $ref: "#/components/examples/test_case_004" required: true responses: - '200': + "200": description: OK content: application/json: @@ -173,10 +173,10 @@ paths: - category - age - sex - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" /pets/{pet_id}: get: summary: Get details of a pet @@ -192,7 +192,7 @@ paths: type: string required: true responses: - '200': + "200": description: Expected response to a valid request content: application/json: @@ -226,11 +226,11 @@ paths: - pet_detail examples: TestCase003: - $ref: '#/components/examples/test_case_003' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' + $ref: "#/components/examples/test_case_003" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" components: securitySchemes: Bearer: @@ -292,10 +292,10 @@ components: value: pet_detail: breeder: BreederName - date_of_birth: '2023-10-31' + date_of_birth: "2023-10-31" pedigree: registration_no: 11111111 - date_of_registration: '2023-10-31' + date_of_registration: "2023-10-31" pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg schemas: ProblemDetailError: @@ -315,10 +315,10 @@ components: content: application/json: schema: - $ref: '#/components/schemas/ProblemDetailError' + $ref: "#/components/schemas/ProblemDetailError" InternalServerError: description: Internal Server Error content: application/json: schema: - $ref: '#/components/schemas/ProblemDetailError' + $ref: "#/components/schemas/ProblemDetailError" diff --git a/documents/forOpenAPISpecification/sample_divided/openapi.yaml b/documents/forOpenAPISpecification/sample_divided/openapi.yaml index b60f2c39..0136cbeb 100644 --- a/documents/forOpenAPISpecification/sample_divided/openapi.yaml +++ b/documents/forOpenAPISpecification/sample_divided/openapi.yaml @@ -21,4 +21,4 @@ components: type: http scheme: bearer bearerFormat: JWT - description: 'Authenthicaiton with bearer token' + description: "Authenthicaiton with bearer token" diff --git a/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml b/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml index fe463158..aa8af366 100644 --- a/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml +++ b/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml @@ -1,167 +1,167 @@ -get: - summary: Search a pet list - description: Search a list of registered pets up to 100. - operationId: getPets - tags: - - pets - parameters: - - name: limit - in: query - description: How many items to return at one time (max 100) - schema: - type: integer - maximum: 100 - format: int32 - required: false - responses: - "200": - description: A paged array of pets - headers: - x-next: - description: A link to the next page of responses - schema: - type: string - content: - application/json: - schema: - type: object - properties: - pets: - type: array - maxItems: 100 - items: - type: object - properties: - id: - type: integer - format: int64 - name: - type: string - maxLength: 50 - category: - type: string - maxLength: 10 - sub_category: - type: string - maxLength: 50 - age: - type: integer - format: int32 - sex: - type: string - maxLength: 6 - note: - type: string - maxLength: 200 - tag: - type: string - maxLength: 20 - required: - - id - - name - - category - - age - - sex - examples: - TestCase001: - $ref: "../examples/pets_get/test_case_001.yaml" - TestCase002: - $ref: "../examples/pets_get/test_case_002.yaml" - "404": - $ref: "../common/responses.yaml#/components/responses/NotFound" - "500": - $ref: "../common/responses.yaml#/components/responses/InternalServerError" - -post: - summary: Register a pet - description: Reginster basic information of new pet. - operationId: postPets - tags: - - pets - requestBody: - content: - application/json: - schema: - type: object - properties: - pet: - type: object - properties: - id: - type: integer - format: int64 - name: - type: string - maxLength: 50 - category: - type: string - maxLength: 10 - sub_category: - type: string - maxLength: 50 - age: - type: integer - format: int32 - sex: - type: string - maxLength: 6 - note: - type: string - maxLength: 200 - tag: - type: string - maxLength: 20 - required: - - id - - name - - category - - age - - sex - required: - - pet - examples: - TestCase004: - $ref: "../examples/pets_post/test_case_004.yaml" - required: true - responses: - "200": - description: OK - content: - application/json: - schema: - type: object - properties: - id: - type: integer - format: int64 - name: - type: string - maxLength: 50 - category: - type: string - maxLength: 10 - sub_category: - type: string - maxLength: 50 - age: - type: integer - format: int32 - sex: - type: string - maxLength: 6 - note: - type: string - maxLength: 200 - tag: - type: string - maxLength: 20 - required: - - id - - name - - category - - age - - sex - "404": - $ref: "../common/responses.yaml#/components/responses/NotFound" - "500": - $ref: "../common/responses.yaml#/components/responses/InternalServerError" +get: + summary: Search a pet list + description: Search a list of registered pets up to 100. + operationId: getPets + tags: + - pets + parameters: + - name: limit + in: query + description: How many items to return at one time (max 100) + schema: + type: integer + maximum: 100 + format: int32 + required: false + responses: + "200": + description: A paged array of pets + headers: + x-next: + description: A link to the next page of responses + schema: + type: string + content: + application/json: + schema: + type: object + properties: + pets: + type: array + maxItems: 100 + items: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + maxLength: 50 + category: + type: string + maxLength: 10 + sub_category: + type: string + maxLength: 50 + age: + type: integer + format: int32 + sex: + type: string + maxLength: 6 + note: + type: string + maxLength: 200 + tag: + type: string + maxLength: 20 + required: + - id + - name + - category + - age + - sex + examples: + TestCase001: + $ref: "../examples/pets_get/test_case_001.yaml" + TestCase002: + $ref: "../examples/pets_get/test_case_002.yaml" + "404": + $ref: "../common/responses.yaml#/components/responses/NotFound" + "500": + $ref: "../common/responses.yaml#/components/responses/InternalServerError" + +post: + summary: Register a pet + description: Reginster basic information of new pet. + operationId: postPets + tags: + - pets + requestBody: + content: + application/json: + schema: + type: object + properties: + pet: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + maxLength: 50 + category: + type: string + maxLength: 10 + sub_category: + type: string + maxLength: 50 + age: + type: integer + format: int32 + sex: + type: string + maxLength: 6 + note: + type: string + maxLength: 200 + tag: + type: string + maxLength: 20 + required: + - id + - name + - category + - age + - sex + required: + - pet + examples: + TestCase004: + $ref: "../examples/pets_post/test_case_004.yaml" + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + maxLength: 50 + category: + type: string + maxLength: 10 + sub_category: + type: string + maxLength: 50 + age: + type: integer + format: int32 + sex: + type: string + maxLength: 6 + note: + type: string + maxLength: 200 + tag: + type: string + maxLength: 20 + required: + - id + - name + - category + - age + - sex + "404": + $ref: "../common/responses.yaml#/components/responses/NotFound" + "500": + $ref: "../common/responses.yaml#/components/responses/InternalServerError" diff --git a/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml b/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml index 5079d376..591b3e3c 100644 --- a/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml +++ b/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml @@ -1,53 +1,53 @@ -get: - summary: Get details of a pet - description: Get details of a pet by specifying its pet ID. - operationId: getPetsPetId - tags: - - pets - parameters: - - name: pet_id - in: path - description: The id of the pet to retrieve - schema: - type: string - required: true - responses: - "200": - description: Expected response to a valid request - content: - application/json: - schema: - type: object - properties: - pet_detail: - type: object - properties: - breeder: - type: string - date_of_birth: - type: string - format: date - pedigree: - type: object - properties: - registration_no: - type: integer - format: int64 - date_of_registration: - type: string - format: date - pedigree_image: - type: string - required: - - registration_no - - date_of_registration - - pedigree_image - required: - - pet_detail - examples: - TestCase003: - $ref: "../examples/pets_pet_id_get/test_case_003.yaml" - "404": - $ref: "../common/responses.yaml#/components/responses/NotFound" - "500": - $ref: "../common/responses.yaml#/components/responses/InternalServerError" +get: + summary: Get details of a pet + description: Get details of a pet by specifying its pet ID. + operationId: getPetsPetId + tags: + - pets + parameters: + - name: pet_id + in: path + description: The id of the pet to retrieve + schema: + type: string + required: true + responses: + "200": + description: Expected response to a valid request + content: + application/json: + schema: + type: object + properties: + pet_detail: + type: object + properties: + breeder: + type: string + date_of_birth: + type: string + format: date + pedigree: + type: object + properties: + registration_no: + type: integer + format: int64 + date_of_registration: + type: string + format: date + pedigree_image: + type: string + required: + - registration_no + - date_of_registration + - pedigree_image + required: + - pet_detail + examples: + TestCase003: + $ref: "../examples/pets_pet_id_get/test_case_003.yaml" + "404": + $ref: "../common/responses.yaml#/components/responses/NotFound" + "500": + $ref: "../common/responses.yaml#/components/responses/InternalServerError" diff --git a/documents/forSQL/index.md b/documents/forSQL/index.md index 5e22c00c..5484059e 100644 --- a/documents/forSQL/index.md +++ b/documents/forSQL/index.md @@ -3,7 +3,7 @@ sidebarDepth: 4 author: フューチャー株式会社 layout: home hero: - name: SQLコーディング規約 + name: SQLコーディング規約 tagline: Future Enterprise Coding Standards for SQL actions: - theme: brand diff --git a/documents/forSlack/index.md b/documents/forSlack/index.md index 9aaeef27..9cf94677 100644 --- a/documents/forSlack/index.md +++ b/documents/forSlack/index.md @@ -3,7 +3,7 @@ sidebarDepth: 4 author: フューチャー株式会社 layout: home hero: - name: 'Slack利用ガイドライン' + name: 'Slack利用ガイドライン' tagline: Slack Usage Guidelines actions: - theme: brand diff --git a/documents/forSlack/slack_usage_guidelines.md b/documents/forSlack/slack_usage_guidelines.md index e10537d0..e497aef8 100644 --- a/documents/forSlack/slack_usage_guidelines.md +++ b/documents/forSlack/slack_usage_guidelines.md @@ -20,9 +20,9 @@ head: また、ユーザーの様々な要望に応えるため、現代のチャットサービスは豊富な機能が提供されている。しかし、各ユーザーの考え方／利用者の感覚が千差万別であるため、ある人によって問題ないとされる行動が、別の人にとっては良くない受け取り方をされることも多い。例えば次のような対立が考えられる。 -* 必要最低限の簡潔なメッセージを送る方が効率的だ／文面が冷たくならないように絵文字や感嘆符（！）を使うべきだ -* 質問はDMで行うべき／チャンネルで行うべき -* times（分報）チャンネルを活用すべき／ノイズなので個人のメモに閉じるべき +- 必要最低限の簡潔なメッセージを送る方が効率的だ／文面が冷たくならないように絵文字や感嘆符（！）を使うべきだ +- 質問はDMで行うべき／チャンネルで行うべき +- times（分報）チャンネルを活用すべき／ノイズなので個人のメモに閉じるべき これら運用方法は利用者の所属する部署やチームごとに自然と決めていくことが多いが、複数のチャンネルで異なった運用方針である場合に混乱をきたすことがしばしばである。また、トレードオフを理解せずに、メールのコミュニケーションモデルを引きずった方針を取ってしまうこともある。異なる文化圏のチームから移籍した時に、ハレーションが起きるケースも多い。 @@ -30,19 +30,19 @@ head: # 適用範囲 -* 「はじめに」章で述べた、一般ユーザー視点での利活用を中心とする -* 次のような特に管理者が関心を持つ事項については対象外とする - * パスワードポリシー／多要素認証の強制 - * 社外メンバー招待／ゲストレベルの調整 - * 監査 +- 「はじめに」章で述べた、一般ユーザー視点での利活用を中心とする +- 次のような特に管理者が関心を持つ事項については対象外とする + - パスワードポリシー／多要素認証の強制 + - 社外メンバー招待／ゲストレベルの調整 + - 監査 # 免責事項 ::: warning 有志で作成したドキュメントである -* フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせて工夫された運営方針が存在する。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している -* 自社のセキュリティポリシーや外部サービス利用ポリシーがある場合は、そちらを優先すること -* Slack Enterprise Grid／Google Workspaceを利用しているため、それらの機能を前提にしている記述がある +- フューチャーアーキテクトには多様なプロジェクトが存在し、それぞれの状況に合わせて工夫された運営方針が存在する。本規約はフューチャーアーキテクトの全ての部署／プロジェクトで利用されているわけではなく、有志が観点を持ち寄って新たに整理したものである。相容れない部分があればその領域を書き換えて利用することを想定している +- 自社のセキュリティポリシーや外部サービス利用ポリシーがある場合は、そちらを優先すること +- Slack Enterprise Grid／Google Workspaceを利用しているため、それらの機能を前提にしている記述がある ::: @@ -70,7 +70,7 @@ head: 理由: -* 管理者権限を持った人しか実行できないオペレーションがあった際、チーム内で解決できる状態を作っておくことが望ましいため +- 管理者権限を持った人しか実行できないオペレーションがあった際、チーム内で解決できる状態を作っておくことが望ましいため # ユーザ向け推奨設定 @@ -80,7 +80,7 @@ head: 理由: -* チャットコミュニケーションにおいて、個人識別におけるアイコン画像の有用性が高いため +- チャットコミュニケーションにおいて、個人識別におけるアイコン画像の有用性が高いため また、GitHub/GitLab、Google Workspace、その他利用サービスも同様のアイコンを利用することで、個人を識別しやすくなる。 @@ -90,7 +90,7 @@ head: 理由: -* Slackではアカウント名のインクリメンタルサーチが強力である。その際、ローマ字でも漢字でもサジェストされる状態にすることでユーザビリティの向上が期待できるため。 +- Slackではアカウント名のインクリメンタルサーチが強力である。その際、ローマ字でも漢字でもサジェストされる状態にすることでユーザビリティの向上が期待できるため。 ## ユーザーグループの推奨 @@ -108,8 +108,8 @@ Slack コネクト等でチャンネル内に社外のメンバーが含まれ 理由: -* 全社的に統一的なプレフィックスを定義することで、外部とのコミュニケーションにて予期しないミスが発生してしまうことを防ぐ目的がある。例えば、内部の進行について相談する発言を、取引先メンバーが在籍するチャンネルに誤投稿してしまう事態を避けるため -* チャンネルはセクションという単位でグルーピング可能となり、従来のように、用途や組織を表現するプレフィックスで並び順を制御する必然性が薄れた +- 全社的に統一的なプレフィックスを定義することで、外部とのコミュニケーションにて予期しないミスが発生してしまうことを防ぐ目的がある。例えば、内部の進行について相談する発言を、取引先メンバーが在籍するチャンネルに誤投稿してしまう事態を避けるため +- チャンネルはセクションという単位でグルーピング可能となり、従来のように、用途や組織を表現するプレフィックスで並び順を制御する必然性が薄れた # 投稿内容ポリシー @@ -119,7 +119,7 @@ Slack コネクト等でチャンネル内に社外のメンバーが含まれ 理由: -* コミュニケーションを迅速・シンプルにするため +- コミュニケーションを迅速・シンプルにするため ## 絵文字や感嘆符を活用する @@ -131,11 +131,11 @@ Slack コネクト等でチャンネル内に社外のメンバーが含まれ 理由: -* より良いコミュニケーション手段を模索すること自体が、コミュニケーションを活性化させ、価値を向上させるため +- より良いコミュニケーション手段を模索すること自体が、コミュニケーションを活性化させ、価値を向上させるため 注意: -* なお、当然ながら他人の名誉を毀損するなど、社会人／プロフェッショナルとしてふさわしくない内容は登録しないこと +- なお、当然ながら他人の名誉を毀損するなど、社会人／プロフェッショナルとしてふさわしくない内容は登録しないこと ## 絵文字リアクションによる積極応答 @@ -155,15 +155,15 @@ Slack コネクト等でチャンネル内に社外のメンバーが含まれ 理由： -* 重複した質問を防ぐため -* 質問事項がチーム／組織に共有されることで、全体の効率が上がるため -* 後から類似の困りごとを持ったメンバーが、キーワード検索で見つけやすくするため +- 重複した質問を防ぐため +- 質問事項がチーム／組織に共有されることで、全体の効率が上がるため +- 後から類似の困りごとを持ったメンバーが、キーワード検索で見つけやすくするため DMの利用を推奨するケース: -* 人事相談、機密事項を含む場合（「機密情報の流出に注意する」章を参照） -* 限られたメンバーのみに、ファイル共有をしたい場合 -* 後から検索させる意味がないやり取り（「最近元気？」と同期に投げる場合など） +- 人事相談、機密事項を含む場合（「機密情報の流出に注意する」章を参照） +- 限られたメンバーのみに、ファイル共有をしたい場合 +- 後から検索させる意味がないやり取り（「最近元気？」と同期に投げる場合など） ## timesの推奨 @@ -171,38 +171,37 @@ timesとは、分報や作業スレッドとも呼ばれ、今取り組んでい 本規約の推奨は次のとおり: -* timesの利用を推奨する -* メンバーごとのtimesチャンネルではなく、スレッドでの利用を推奨する -* timesスレッドは、他のメンバーは参照しても参照しなくてもどちらでも良い +- timesの利用を推奨する +- メンバーごとのtimesチャンネルではなく、スレッドでの利用を推奨する +- timesスレッドは、他のメンバーは参照しても参照しなくてもどちらでも良い 理由: -* スレッド単位であれば、本チャンネル側のノイズになることはない。参加メンバーが多い場合は、times専用のチャンネルを作成すれば良い -* メンバーごとの times チャンネルは、チャンネルが必要以上に増えるので推奨しない -* 必要に応じて、作業状況を本人に確認（ポーリング）しなくても把握することができる -* ハマったことや調べたことが、後々キーワード検索で見つかり、新規参画者の助けになることも多い +- スレッド単位であれば、本チャンネル側のノイズになることはない。参加メンバーが多い場合は、times専用のチャンネルを作成すれば良い +- メンバーごとの times チャンネルは、チャンネルが必要以上に増えるので推奨しない +- 必要に応じて、作業状況を本人に確認（ポーリング）しなくても把握することができる +- ハマったことや調べたことが、後々キーワード検索で見つかり、新規参画者の助けになることも多い timesスレッド作成者の注意事項: -* times内とはいえ、他の人が不快になるような発言や不適切な利用は避ける（チームメンバーが閲覧可能であることを忘れない） +- times内とはいえ、他の人が不快になるような発言や不適切な利用は避ける（チームメンバーが閲覧可能であることを忘れない） timesスレッド内のメンション: -* timesスレッドのコメント数は100以上になることもあり、途中で他メンバーに相談事などでメンションを飛ばすと、呼ばれたメンバーには「該当のスレッドの全コメントをチェックしたほうが良いのか」といった迷いが生じる。そのため、times内ではなく相談は別メッセージに切り出して行うことを推奨する -* なお、timesの投稿を読んで欲しいときは、timesスレッドでメンションしても良い -* timesのメンションを受けたユーザーが、その後の投稿の通知を受け取りたくない場合は、そのスレッドの通知を切ることで対応する +- timesスレッドのコメント数は100以上になることもあり、途中で他メンバーに相談事などでメンションを飛ばすと、呼ばれたメンバーには「該当のスレッドの全コメントをチェックしたほうが良いのか」といった迷いが生じる。そのため、times内ではなく相談は別メッセージに切り出して行うことを推奨する +- なお、timesの投稿を読んで欲しいときは、timesスレッドでメンションしても良い +- timesのメンションを受けたユーザーが、その後の投稿の通知を受け取りたくない場合は、そのスレッドの通知を切ることで対応する timesスレッドでメンションを飛ばすと、その後の投稿によってメンション先のユーザーに通知が飛んでしまうのではないか？という懸念への考え方: -* 該当スレッドのフォローを外せば良いので、上記観点でメンションを行う／行わないの判断は行わなくても良い。前述の通り、timesのコメントを（全て）読んで欲しい否かで決める - +- 該当スレッドのフォローを外せば良いので、上記観点でメンションを行う／行わないの判断は行わなくても良い。前述の通り、timesのコメントを（全て）読んで欲しい否かで決める ## メッセージ（スレッドのトップ）は具体的に書く チャンネルのメッセージ（スレッド先頭の投稿）では、話題を端的に表現する。ただし、返信スレッドの中を確認しないと内容が分からないようなメッセージ（タイトル）は非推奨とする。 -| | メッセージ（スレッド先頭の投稿） | -| :-------- | :--------------------------------------------------------------------------------------------------------------------- | +| | メッセージ（スレッド先頭の投稿） | +| :--------- | :--------------------------------------------------------------------------------------------------------------------- | | ✅推奨例 | @mirai チケット \#4191 foo bar failed のビルドエラーの解消についての相談です。スタックトレースはスレッド内に記載します | | ❌非推奨例 | レビュー依頼 | @@ -210,8 +209,8 @@ timesスレッドでメンションを飛ばすと、その後の投稿によっ 参考: -* [Slackで要件を書かずに「質問があります。詳細はスレッドに記載」をやめたほうがいい理由 \- CARTA TECH BLOG](https://techblog.cartaholdings.co.jp/entry/better_slack_communication) -* [リモートワーク時代を生き抜くAI・機械学習チームの働き方 \- エムスリーテックブログ](https://www.m3tech.blog/entry/2024/12/07/110000) +- [Slackで要件を書かずに「質問があります。詳細はスレッドに記載」をやめたほうがいい理由 \- CARTA TECH BLOG](https://techblog.cartaholdings.co.jp/entry/better_slack_communication) +- [リモートワーク時代を生き抜くAI・機械学習チームの働き方 \- エムスリーテックブログ](https://www.m3tech.blog/entry/2024/12/07/110000) ## メッセージのURLを活用する @@ -229,9 +228,9 @@ Also send to channel を利用することで、スレッド内の投稿をチ 本規約の推奨は以下の通り: -* 過去のスレッドでやり取りを再開した場合に、チャンネルに在籍するメンバーに通知する目的で用いる -* スレッド内で重要な決定事項に至った場合は、メンバーに周知する目的で用いる -* スレッド内のやり取りを細かくAlso send to channelすると、スレッドを用いる意味が薄れるので、利用頻度は抑えるように意識する +- 過去のスレッドでやり取りを再開した場合に、チャンネルに在籍するメンバーに通知する目的で用いる +- スレッド内で重要な決定事項に至った場合は、メンバーに周知する目的で用いる +- スレッド内のやり取りを細かくAlso send to channelすると、スレッドを用いる意味が薄れるので、利用頻度は抑えるように意識する ## 広めの通知に注意する @@ -241,36 +240,36 @@ Also send to channel を利用することで、スレッド内の投稿をチ 理由: -* `@channel` はSlackを見ていないユーザにも通知が飛ぶため、休暇中のメンバー等にも影響がある。受取側で制御すべきという考えもあるが、システム障害対応など優先度の高い問い合わせのために、あえてOFFにしていないメンバーも存在することを考えると、なるべく利用を避けた方が無難である +- `@channel` はSlackを見ていないユーザにも通知が飛ぶため、休暇中のメンバー等にも影響がある。受取側で制御すべきという考えもあるが、システム障害対応など優先度の高い問い合わせのために、あえてOFFにしていないメンバーも存在することを考えると、なるべく利用を避けた方が無難である 利用して良い場合: -* システム障害時など、重大かつ緊急度が高い場合は `@channel` を使っても良い +- システム障害時など、重大かつ緊急度が高い場合は `@channel` を使っても良い ### `@here` メールのCCに似た意図で `@here` を使うことは禁止とする。 -推奨ケース +推奨ケース ```txt -@真野 @村田 ○○の件ですが\~ +@真野 @村田 ○○の件ですが\~ ``` -NG（メールのCC的な形で `@here` を追加） +NG（メールのCC的な形で `@here` を追加） ```txt -@真野 @村田 @here ○○の件ですが +@真野 @村田 @here ○○の件ですが ``` 理由: -* メールのCC的な参考情報であれば、`@here` を付けずに、チャンネルの未読通知で後で見ることができるため -* 真に必要ではないときに通知が飛ぶことが常態化すると、`@here` の緊急性やアクションを求める意味合いが弱まり、真に必要なときに読み飛ばされてしまう可能性が上がるため（「狼少年」現象） +- メールのCC的な参考情報であれば、`@here` を付けずに、チャンネルの未読通知で後で見ることができるため +- 真に必要ではないときに通知が飛ぶことが常態化すると、`@here` の緊急性やアクションを求める意味合いが弱まり、真に必要なときに読み飛ばされてしまう可能性が上がるため（「狼少年」現象） 利用して良い場合: -* 全員にアクションを促す連絡事項を行う場合。例えば、チーム全体イベントへの出欠可否を確認する連絡など +- 全員にアクションを促す連絡事項を行う場合。例えば、チーム全体イベントへの出欠可否を確認する連絡など ## メンション範囲は適切に @@ -279,7 +278,7 @@ NG（メールのCC的な形で `@here` を追加） 原則、レビュー依頼や確認依頼など、行動してほしい時にメンションを付けるものとする。「@mirai ありがとうございます！」「@mirai 承知しました！」等の挨拶にメンションを付けると、通知が来てノイズになるため非推奨とする。メンションを付けず「ありがとうございます！」とすると良い。 ::: tip 情報提供依頼系など善意やり取りはきちんとフィードバックする -情報提供依頼はSlackと親和性が良いタスクである。この際、情報提供の依頼者は、回答してもらった人に対して、:+1: 絵文字だけのリアクションを取る場合があるが、フィードバック付きでコメントを返すことが望ましい。情報提供者としても、その情報が役立ったのか、またそうでないかの関心は強いためである。 +情報提供依頼はSlackと親和性が良いタスクである。この際、情報提供の依頼者は、回答してもらった人に対して、:+1: 絵文字だけのリアクションを取る場合があるが、フィードバック付きでコメントを返すことが望ましい。情報提供者としても、その情報が役立ったのか、またそうでないかの関心は強いためである。 もし、フィードバックが難しい場合や、スレッド投稿数をなるべく減らしたいなどの意図がある場合は、複数のリアクションを返し感謝の意を強調すると良い。 👍️🎉☺\[神\] のようなイメージである。 ::: @@ -293,9 +292,9 @@ NG（メールのCC的な形で `@here` を追加） 理由: -* 仕事とプライベートにメリハリを持たせることで、成果の向上を期待できるため -* （システム障害等）緊急時の依頼と混同してしまうため。次回出勤時の対応で良いものと区別すること -* Slackのアップデートにより、チャンネル投稿に閉じずスレッド投稿へも予約投稿が可能となった +- 仕事とプライベートにメリハリを持たせることで、成果の向上を期待できるため +- （システム障害等）緊急時の依頼と混同してしまうため。次回出勤時の対応で良いものと区別すること +- Slackのアップデートにより、チャンネル投稿に閉じずスレッド投稿へも予約投稿が可能となった ::: tip 受け取り側で制御する方針 システム障害時などの緊急時は電話連絡とし、メンションに対する即対応を求めない取り決めを行うのであれば、受け取り側で通知時間を設定し、送る側は送信時間に気を遣わない運用も可とする。ただし、時間外に通知を受け翌営業日に対応しようと考えたが翌営業日には忘れているような場合、受け取り側で通知を受けた時点でリマインダーを仕込んだり、アクティビティ \> @メンション を定期的に確認するような工夫をする。 @@ -308,13 +307,13 @@ NG（メールのCC的な形で `@here` を追加） ::: tip ステータス機能で「休暇中🏝️」にすればよいのではないか ステータス機能でもチームメンバーに不在であるという状態を表明できる。しかし、次の観点で表示名での表明を推奨する。 -* いつから、いつまで休暇なのかステータスでは不明である - * 期間が分かれば、予約投稿で休暇明けに投稿するなどのアクションがすぐ取れる -* 休暇だけでなく出張中などの情報も提示できる - * 例えば、海外出張なので時差があることが分かれば、チームメンバーにどれくらいでレスポンスが来そうか予想ができるようになる -* ステータス変更に気が付きにくい - * メンションを付けて投稿する時に常時表示されるわけではないので、ステータスは見過ごされる可能性が高い -::: +- いつから、いつまで休暇なのかステータスでは不明である + - 期間が分かれば、予約投稿で休暇明けに投稿するなどのアクションがすぐ取れる +- 休暇だけでなく出張中などの情報も提示できる + - 例えば、海外出張なので時差があることが分かれば、チームメンバーにどれくらいでレスポンスが来そうか予想ができるようになる +- ステータス変更に気が付きにくい + - メンションを付けて投稿する時に常時表示されるわけではないので、ステータスは見過ごされる可能性が高い + ::: ## 可読性を上げるための書式設定 @@ -326,14 +325,14 @@ NG（メールのCC的な形で `@here` を追加） 理由: -* 相談相手も裏取りとしてスタックトレースの内容を検索することが多々あるため -* 後から同様の困り事を持った人が、キーワード検索で見つけにくくなるため -* 長いログをそのまま貼り付けるとスレッドを広く埋め尽くしてしまうが、テキストスニペットを使えば1投稿あたりのデフォルト表示域を制限できる +- 相談相手も裏取りとしてスタックトレースの内容を検索することが多々あるため +- 後から同様の困り事を持った人が、キーワード検索で見つけにくくなるため +- 長いログをそのまま貼り付けるとスレッドを広く埋め尽くしてしまうが、テキストスニペットを使えば1投稿あたりのデフォルト表示域を制限できる 次の場合は、スクリーンショットなどの画像で共有しても良い。 -* コピーできないエラー表示など、テキストでの情報提供が難しい場合 -* （相談相手が、コピー範囲などを独自判断で狭められることを防ぐなどの理由で）スクリーンショットでの共有を希望する場合 +- コピーできないエラー表示など、テキストでの情報提供が難しい場合 +- （相談相手が、コピー範囲などを独自判断で狭められることを防ぐなどの理由で）スクリーンショットでの共有を希望する場合 ::: tip テキストスニペット利用時は、タイトル（ファイル名）に拡張子をつける Slackはテキストスニペットに設定されたタイトルをそのままファイル名としてダウンロードするよう動作する。この際拡張子が設定されていないとSlack内でそのままファイルを開くことができなくなってしまう。 @@ -346,9 +345,9 @@ Slackはテキストスニペットに設定されたタイトルをそのまま :::tip メッセージ通知にも気をつける 画面投影やWebミーティングでの画面共有時、意図しないメッセージ通知が見えてしまう事がある。Slackの通知設定にて次に示す設定を施すことで防ぐことが可能なので活用すると良い。 -* 通知自体をOFFにする -* 通知はOFFにしないが、メッセージ内容は非表示にする -::: +- 通知自体をOFFにする +- 通知はOFFにしないが、メッセージ内容は非表示にする + ::: ## ファイルの共有に注意する @@ -356,24 +355,24 @@ Slackのファイル共有は便利であるが、ファイルのオーナー（ 推奨する運用: -* Google Driveなどにファイルをアップロードする -* Google Drive側で適切な権限に絞り込む +- Google Driveなどにファイルをアップロードする +- Google Drive側で適切な権限に絞り込む 理由: -* Google Drive側で権限設定が可能 -* Slack上にアップロードされたファイルが、別のチャンネルに再アップロードされて収集がつかなくなるといったケースを防ぎ、統制を図るため +- Google Drive側で権限設定が可能 +- Slack上にアップロードされたファイルが、別のチャンネルに再アップロードされて収集がつかなくなるといったケースを防ぎ、統制を図るため 該当しないケース: -* 社外勉強会の登壇資料など、一般に「公開済み／公開予定 」のファイルはアップロードして良い +- 社外勉強会の登壇資料など、一般に「公開済み／公開予定 」のファイルはアップロードして良い Google DriveのURL共有時プレビュー表示について: -* 表紙がプレビューされるが、次の理由により問題ないという立場を取る。 - * プレビュー表示されるのは1枚目（1シート目）であり、通常は表紙ページが見られるのみ - * ファイルが存在すること自体は知られて良い（チャンネルに投稿しているため）と考えられる - * なにか問題があれば、プレビュー表示を行わない操作がSlack上で可能である +- 表紙がプレビューされるが、次の理由により問題ないという立場を取る。 + - プレビュー表示されるのは1枚目（1シート目）であり、通常は表紙ページが見られるのみ + - ファイルが存在すること自体は知られて良い（チャンネルに投稿しているため）と考えられる + - なにか問題があれば、プレビュー表示を行わない操作がSlack上で可能である ## プライベートチャンネルの投稿に対する引用 @@ -385,4 +384,4 @@ Google DriveのURL共有時プレビュー表示について: 参考： -* [メルカリ社内Slack利用ガイドラインを一挙公開しました〜！！\#メルカリな日々 | mercan (メルカン)](https://careers.mercari.com/mercan/articles/23325/) [mercari-Slack-guidelines/Slack\_Guidelines\_Ja.md at master](https://github.com/mercari/mercari-slack-guidelines/blob/master/Slack_Guidelines_Ja.md) +- [メルカリ社内Slack利用ガイドラインを一挙公開しました〜！！\#メルカリな日々 | mercan (メルカン)](https://careers.mercari.com/mercan/articles/23325/) [mercari-Slack-guidelines/Slack_Guidelines_Ja.md at master](https://github.com/mercari/mercari-slack-guidelines/blob/master/Slack_Guidelines_Ja.md) diff --git a/eslint.config.mjs b/eslint.config.mjs new file mode 100644 index 00000000..7519aaaa --- /dev/null +++ b/eslint.config.mjs @@ -0,0 +1,29 @@ +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import js from "@eslint/js"; +import { FlatCompat } from "@eslint/eslintrc"; +import pluginVue from "eslint-plugin-vue"; +import eslintConfigPrettier from "eslint-config-prettier"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); +const compat = new FlatCompat({ + baseDirectory: __dirname, + recommendedConfig: js.configs.recommended, + allConfig: js.configs.all, +}); + +export default [ + { + ignores: ["node_modules/", "docs/", ".vitepress/cache/"], + }, + ...compat.extends("standard"), + ...pluginVue.configs["flat/recommended"], + { + rules: { + "no-var": "error", + "prefer-const": "error", + }, + }, + eslintConfigPrettier, +]; diff --git a/index.md b/index.md index 40c86abd..f5b8ee53 100644 --- a/index.md +++ b/index.md @@ -2,10 +2,10 @@ layout: home title: Future Enterprise Coding Standards hero: - name: Future Enterprise Coding Standards + name: Future Enterprise Coding Standards # text: '' tagline: フューチャー株式会社が作成するエンタープライズ領域に特化したコーディング規約 - actions: + actions: - theme: brand text: Javaコーディング規約 link: ./documents/forJava/ diff --git a/package.json b/package.json index f5477af9..78fa2d53 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,9 @@ "watch": "vitepress dev . --open", "build": "vitepress build .", "install": "npm install --global mermaid-filter", - "lint": "eslint . .vitepress --ext .js,.vue", + "lint": "npm run lint:format && npm run lint:js", + "lint:js": "eslint . .vitepress", + "lint:format": "prettier . --list-different", "copy": "npm-run-all copy:*", "copy:git": "cp -r documents/forGitBranch/img docs/documents/forGitBranch/img", "copy:markdown": "cp -r documents/forMarkdown/future_muscle_partner/docs/future_muscle_partner_abstract.png docs/documents/forMarkdown/future_muscle_partner/docs/future_muscle_partner_abstract.png", @@ -41,13 +43,11 @@ }, "homepage": "https://future-architect.github.io/coding-standards/", "devDependencies": { - "eslint": "^8.0.0", - "eslint-config-prettier": "^8.3.0", + "@eslint/eslintrc": "^3.2.0", + "@eslint/js": "^9.17.0", + "eslint": "^9.17.0", + "eslint-config-prettier": "^9.1.0", "eslint-config-standard": "^17.1.0", - "eslint-plugin-import": "^2.16.0", - "eslint-plugin-node": "^11.0.0", - "eslint-plugin-promise": "^6.0.0", - "eslint-plugin-standard": "^4.0.0", "eslint-plugin-vue": "^9.0.0", "markdown-it-footnote": "^4.0.0", "markdown-it-task-lists": "^2.1.1",