本リポジトリは、C++の日本語リファレンスサイトcpprefjpのコンテンツを扱っています。私たちは、本サイトを一緒に編集していただける方を歓迎いたします。
ここでは、本サイトおよびそのMarkdownテキストを扱う本リポジトリを編集するにあたってのガイドラインをまとめます。
本サイトが提供するコンテンツは、全ての関数、全てのクラスにひとつ以上のサンプルコードを提供することを目標としています。これによって、ユーザーがその機能をどのように使えばよいのかの道を示せるようにし、その機能をどのような用途で使えるかを示せるようにします。
本サイトが提供するコンテンツは、編集者間での合意がとれるものである限りにおいて、「提供しなくてよい情報」というものはないと考えています。情報を書きすぎてはいけないということはありませんので、情報不足と思われる場所を見つけたら、現在の本サイトのスコープに収まる限りは追記していただいてかまいません。
スコープを超えるコンテンツを提供したい場合には、pull requestかissueを発行して、合意をとってください。
本サイトは、C++の規格書や他のリファレンスサイトの翻訳を提供するサイトではありません。本サイトのコンテンツは、仕様を理解した編集者が自分たちなりの言葉でC++機能の解説を書き、提供します。
本サイトには、多くの方がコンテンツを提供しています。そのため、ほかの人が書いたコンテンツを編集することも少なくありません。編集者間での考え方の違いによるトラブルを防止するために、ほかの人が書いたコンテンツを編集する際は、以下のフローで修正の仕方を検討していただければと思います：
- 修正方針がわからない・複数考えられるが決めかねるようならissueを作って確認をとる
- 修正はできるが、修正内容について修正者以外の合意・確認が必要そうならpull requestを作る
- 元の記事を書いた人に伝えておきたいだけなら、事前にコメントを飛ばしたうえで直接修正する
- 1.〜3.のようなことが何もなければ直接修正してかまわない。ただし、修正の理由や根拠は、修正内容かコミットメッセージのどちらかでフォローしておいたほうがよい
なお、「ほかの人が書いたコンテンツ」には、本サイトの方針も含まれます。方針の改訂を提案する場合にも、上記フローでお願いします。
本サイトでは多くのコンテンツを提供していますが、考えられる限り全ての情報を記載しているわけではありません。現在の本サイトが提供している範囲を超えるコンテンツを提供したい場合には、issueもしくはpull requestを作って合意をとってください。
本サイトの編集にあたって、編集者間の相談にはissueを使用してください。編集者間で直接やりとりしていただいてもかまいませんが、本サイトの記録として残したほうがよいやりとりであると判断した場合には、そのやりとりを本リポジトリのissueに貼り付けたり、リンクを貼ったりしていただければと思います。
ただし、編集者間の合意が必要あるものは、編集者間の直接のやりとりではなく、必ず本リポジトリのissueかpull requestで相談してください。オープンに議論できるものについては、管理者も同様です。
本サイトで書くことが決まっているタスクを確認するには、issueを参照してください。「TASK」ラベルが付いているもので、担当者がついていないものがあれば、ぜひとも引き取ってください。
push権限を持っている方は、Pull Requestのレビューとマージもぜひお願いします。
Pull Requestを送っていただいた方には、管理者から後ほどpush権限をお渡しします。権限の譲渡は管理者がする必要がありますが、レビューとマージは、ほかのpush権限保持者がしていただいてかまいません。
Pull Requestのレビューが滞っていた場合、Pull Requestの提出者の方は、cpprefjpのpush権限保持者に対して、個人的にレビューを依頼してもかまいません。push権限保持者がだれかは、以下のページから確認できます：
- cpprefjp people
- 権限保持者の確認に使用できます
- cpprefjp contributors
- 各人が本サイトにどれくらいコントリビュートしているかを確認できます
ただし可能な限り、レビュアーとの技術的な議論はPull Request上で行っていただけると助かります。これは、議論を記録として残すことが目的です。
- コミットメッセージに厳密な書式は設けない
- 人によっては「〜を修正」のように書き、またある人は「fix ...」のように書きます。コミットメッセージは修正内容がわかることが大事で、書式はそれほど重要ではないという考えです
- また、本リポジトリが、英語の情報を元に日本語情報を提供する、という特性上、コミットメッセージが日本語と英語どちらであっても編集者が困ることはないはずですので、日本語か英語であれば、どちらで書いてもよいものとします
- コミットメッセージの内容としては、とくに自分以外の人が書いた文章を編集する際には、コミットメッセージに「なぜそのように編集したのか」をできるだけ書いたほうがよいです。これは、経緯を振り返りやすくすることが目的です
- 強制プッシュ
git push -fやgit push --forceといったコマンドは、リポジトリの設定で、masterブランチに対してはできないようにしてあります。これは、masterブランチは壊してはならないという理由によるものです- masterブランチ以外には強制プッシュできますので、Pull Request用のトピックブランチのコミットを整理する、といった目的などで使用していただいて大丈夫です
- 署名付きコミット
- GPGによって署名が付いたコミットをすると、GitHub上でコミットに「Verified」と表示されます。このようなコミットがあると、リポジトリの信頼度が向上するため、強制ではありませんが署名を付加することを推奨します
- cpprefjpでは、GitHub Actionsを使用して、コミットされるたびにMarkdown形式からHTML形式に変換して、GitHub Pagesとしてデプロイを行っています
- その変換時になんらかのエラーが発生した場合には、手元で修正して再度git pushを行うことになります
- 変換エラーではなく、GitHub Pagesリポジトリへのgit pushに失敗した場合 (buildアクションの実行中に新たなコミットがgit pushされた場合など) には、そのbuildアクションに対してRe-run jobを実行し、再度変換を行ってください
push権限を持っていない方は、pull requestで何らかの編集を行うところからはじめてください。タスクを引き取っていただける場合には、タスクのissueに「やります」とコメントを書いていただければ、担当をお渡しします。
管理者からpush権限をお渡しする申請が届いた場合には、引き受けていただけると幸いです。