📑
Git リポジトリにとりあえず作るドキュメントたち
GDG Greater Kwansai Padawan Organizer のたくてぃん (@taku_ting) です。
GDG Kwansai の Advent Calendar 2024 19 日目は私からドキュメントのお話。
Git リポジトリに私がよく書くドキュメントは最低限、
README.mdCONTRIBUTING.md
と、
ソフトウェアの説明自体が必要である場合(開発初期段階でドキュメントが揃っていない場合など)は
.docs/DesignDoc.md
また、サーバーアプリケーションの場合やインストール方法が複雑な場合は追加で
.docs/deploy/(docker|k8s)/README.md
を書いています。
README.md
まず、最初に読んでもらう場所はやはりここでしょう。
私は以下のようなフォーマットをよく使用します。
# [title]
[2,3文の概要]
## Usage
[使用方法]
[起動コマンド (ライブラリの場合はインストール方法と import 文)]
### [使用例1]
[開く画面(URL) (ライブラリの場合は関数呼び出し例)]
[ドキュメントサイトが別にある場合はリンクと誘導]
## Deploy
### Running with Docker Compose
Refer to the documentation in [Docker Compose Deployment](.docs/deploy/docker/README.md) for instructions on how to deploy using Docker Compose.
## Contributing
Refer to the documentation in [CONTRIBUING.md](CONTRIBUTING.md).
README は導線として活用しつつ、ベーシックな使い方はいくつか README を見るだけで完結出来るようにしておくと個人的には気持ちが良いです！
- 例
- サーバーアプリケーション tingtt/urlshortener -
README.md - ライブラリ / CLI ツール tingtt/qtffilst -
README.md
- サーバーアプリケーション tingtt/urlshortener -
CONTRIBUTING.md
続いては開発者向け。
- Code of Conduct
- Contribute 手順・ブランチ命名規則
- コーディングスタンダード
- ビルド手順
- テスト手順
- コード設計
などを書くとよいかと思います。
Fork してもらう例 (Go言語を使用しているプロジェクト)
# Contributing to [title]
Thank you for considering contributing to the project! We welcome contributions in all forms.
## Code of Conduct
Please adhere to the [Go Community Code of Conduct](https://go.dev/conduct) when interacting with others in the project.
## How to Contribute
1. Fork the repository.
2. Create a new branch (`git checkout -b my-feature-branch`).
3. Make your changes.
- Please run `make test` for lint, staticcheck, and tests.
4. Commit your changes (`git commit -m 'Add some feature'`).
5. Push to the branch (`git push origin my-feature-branch`).
6. Create a new Pull Request.
## Build
### Docker
To build the Docker image, use the following command:
\```bash
docker build .
\```
## Testing
\```sh
make test
# will run `go test ./... -short -parallel 10`
make testall
# will run `go test ./... -parallel 10`
\```
## Issue Reporting
If you encounter a bug or have a feature request, please open an issue in the GitHub repository.
ブランチ運用やコミットメッセージについて明記する場合 (TypeScript を使用しているプロジェクト)
昔に書いたものをそのまま持ってきました。
- ブランチ運用
- コミットメッセージのフォーマット
- ディレクトリ構造
- コーディングスタンダード
- テスト
について書いています。
# Contributing
## Docs
[他ドキュメントのリンクなど]
## Branch
[git-flow](https://nvie.com/posts/a-successful-git-branching-model/) を採用
| ブランチ名 | ブランチ名 | 用途 | ブランチ元 | マージ先 |
| ---------- | ---------- | --------------------- | ---------- | ----------------- |
| `main` | | Production | | |
| `hotfix` | | バグ修正 (Production) | `main` | `main`, `develop` |
| `release` | | Staging | `develop` | `main`, `develop` |
| `develop` | | Development | `main` | |
| | `feat/*` | 機能追加(テスト含む) | `develop` | `develop` |
| | `fix/*` | バグ修正 | `develop` | `develop` |
| | `docs/*` | ドキュメント類 | `develop` | `develop` |
| | `ci/*` | git, 自動化など | `develop` | `develop` |
| | `chore/*` | 雑多 (deprecated) | `develop` | `develop` |
## Commit
\```bash
# 例: 機能に関するコミット
git commit -m 'feat(機能名): 変更内容'
\```
コミットメッセージのフォーマットは [conventional-changelog/commitlint](https://github.com/conventional-changelog/commitlint) の`README.md`を参照してください。
## Pull Request
`develop`, `main` ブランチへのマージは必ず Pull Request を使用してください。
### Name
\```
feat(機能名): 変更内容
\```
[コミット名](#commit)のフォーマットに則って命名してください。
### Merge
Pull Request をマージする際は、可能であれば rebase をしてください。
## Directory Architecture
[Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) を採用
| path | レイヤー |
| -------------------- | --------------------------- |
| `src/` | Frameworks & Drivers |
| `interface-adapter/` | Interface adapter |
| `usecase/` | Application Buisiness Rules |
| `domain/` | Enterprise Buisiness Rules |
## Coding Standards
### Lint
Perttier, ESLintを使用してください。
[husky](https://github.com/typicode/husky) によってコミット時に自動でフォーマットが実行されます。
#### Setup IDE (standard: VSCode)
\```bash
# Setup extensions
$ code --install-extension dbaeumer.vscode-eslint
$ code --install-extension esbenp.prettier-vscode
$ cat << EOF > ./.vscode/settings.json
{
"[javascript]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescript]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[javascriptreact]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescriptreact]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
}
}
EOF
\```
### TypeScript
基本は [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html) に則って記述してください。
#### interface
- インターフェースの名称は、末尾に`I`を付けてください。
- インターフェースを同名のクラスでマージしないでください。
- インターフェースの定義がマージされている場合、クラスが実装済みであるか検証できないため。
\```diff
- export interface Calculator { ... }
- export class Calculator implements Calaculator { ... }
+ export interface CalculatorI { ... }
+ export class Calculator implements CalculatorI { ... }
\```
#### import
以下の場合はエイリアスを使用してください。
- [Directory Architecture](#DirectoryArchitecture) に示した Clean Architecture の各レイヤーを跨いで import する場合
- `test/` ディレクトリ内のテストコードから import する場合
| path | import |
| -------------------- | ----------------------------------- |
| `src/` | `import * from 'src'` |
| `interface-adapter/` | `import * from 'interface-adapter'` |
| `usecase/` | `import * from 'usecase'` |
| `domain/` | `import * from 'domain'` |
\```diff
- import * from '../../domain/calculator'
+ import * from 'domain/calculator'
\```
### Unit Test
[JEST](https://jestjs.io/docs/getting-started)を使用
テストコードサンプルは[TypeScript JEST](https://basarat.gitbook.io/typescript/intro-1/jest)を参照
test command
\```sh
bun jest tests/
bun jest tests/domain/calculator/
bun jest tests/domain/calculator/calculator.test.ts
\```
- 例
- Fork してもらう想定 (Go) tingtt/urlshortener -
CONTRIBUTING.md
- Fork してもらう想定 (Go) tingtt/urlshortener -
.docs/DesignDoc.md
こちらは企画書的なものです。
チーム全員が Markdown に慣れていてリポジトリを見れるのであればリポジトリ内で書ききってしまうことも多いです。
# Design Doc: [title]
## Objective
[開発目的]
## Goal, Non goal
### Goal
[実現すること]
### Non goal
[実現しないこと]
## Background
[企画背景]
## High Level Structure
[具体的な設計 (パッケージ相関図など)]
## Security Considerations
[セキュリティの考慮事項]
## Privacy Considerations
[プライバシーの考慮事項]
## Open Issues
[現時点で存在する課題]
## References
[参照ドキュメントなど]
.docs/deploy/(docker|k8s)/README.md
最後にデプロイ手順のドキュメントです。
特に、サーバーに各自デプロイして使用してもらう中で、
- APIキーなどのセッティング
- コンフィグファイル
- 永続データの保存先ディレクトリ
などに気をつける必要があるなら書いておくが吉と考えています。
OAuth2 の設定が必要な場合の例
# Deploy with Docker Compose
## 1. OAuth2 Configuration and .env File
First, set up at least one OAuth2 provider.
- **Google Cloud**
- [Create OAuth client ID](https://console.cloud.google.com/apis/credentials/oauthclient)
- **GitHub**
- [Register a new OAuth application](https://github.com/settings/applications/new)
Encode the OAuth2 client credentials with base64 and store them in a `.env` file.
\```sh
echo -n '<Your client ID>;<Your client secret>' | base64
\```
Create a `.env` file with the following contents:
\```env
JWT_SECRET=<base64-encoded JWT secret>
OAUTH2_GOOGLE=<base64-encoded OAuth2 client credential set>
OAUTH2_GITHUB=<base64-encoded OAuth2 client credential set>
\```
## 2. Create `compose.yaml`
Create a `compose.yaml` file to define services.
\```yaml
[compose.yaml のサンプル]
\```
まとめ
私が Git リポジトリ内によく書いているドキュメントについての紹介でした。
参考にしていただければ嬉しいです！
-
README.md- 簡易的な使用方法
- ほかドキュメントへの導線
-
CONTRIBUTING.md- PR / MR 作成までの手順
- ディレクトリ構成
- コーディングスタンダード
- テスト
- lint / 静的解析
-
.docs/DesignDoc.md- 企画・ソフトウェアの説明
-
.docs/deploy/(docker|k8s)/README.md- デプロイ手順
Discussion