oss-gate/first-feedback-guidebook

OSS Gateワークショップ参加者の方からよく寄せられる疑問への回答を元にした、初めてのフィードバックの手引き

これでできる！ はじめてのOSSフィードバックガイド ～ #駆け出しエンジニアと繋がりたい と言ってた私が野生のつよいエンジニアとつながるのに必要だったこと～

OSS Gateワークショップ参加者の方からよく寄せられる疑問への回答を元にした、初めてのフィードバックの手引き。

頒布情報

• 商業版「これでできる！ はじめてのOSSフィードバックガイド -「つよいエンジニア」になるための実績の育て方- （技術の泉シリーズ 紙媒体オンデマンド印刷）：v1.2を底本として、一部誤記等が訂正されています。それ以外の内容的な差異はありません。すぐに紙媒体で入手したい方向けです。（2020年5月～）
• 書いた人のBOOTHで電子書籍版（EPUB/PDF）のダウンロード販売（2020年2月29日～）
• Amazon Kindle ダイレクト・パブリッシング （2020年2月29日～）
• 同人誌委託通販サービス等何らかの手段で紙版＋電子書籍ダウンロードカードの通販（2020年4月～？）

頒布物は、このリポジトリの内容を後述の手順でビルドした物と変わりありません。 値段が付いている物については、「ビルド環境を整える時間と手間をお金で買う」「書いた人にお布施する」というつもりでご購入頂ければ幸いです。

訂正情報・変更点

• 最新の原稿との比較
  • v1.4からの全変更点
• v1.4：電子書籍4刷（2021年11月9日付）
  • 「はじめに」に「OSS」という語への注釈を追加した。
  • 「第12章 仕事が忙しくてOSS活動に時間を割けない！」内の「12.2 フィードバックしないと損をする！」において、MongoDB、Redis、Kafkaなどが採用したライセンスの補足説明を追加。
  • 「第14章 ライセンスについてより正確に知る」内の「14.2 オープンソースの定義って？」において、BSDライクライセンスをBSDライセンスと同一視する考え方にも触れるようにした。また、各種ライセンスが自由なソフトウェアライセンスにあてはまるかどうかのFSFによる見解について言及するようにした。
  • 「第14章 ライセンスについてより正確に知る」内の「14.4 オープンソースと自由なソフトウェア」において、オープンソースと自由なソフトウェアの関係の記述を、より正確な内容に改めた。
  • 全体に渡って細かい表現を改めて、読みやすさを向上させた（つもり）。
  • v1.3からの全変更点
• v1.3：電子書籍3刷（2021年10月26日付）
  • 「第5章 どう報告すればいいのか分からない」について、専用の検証環境を用意せず普段使いの環境で再現手順を特定する方法から解説するよう、全体の構成を改めた。
  • 「第6章 英語での報告の仕方が分からない」において、一部の節の順番を入れ換え、機械翻訳の取り扱いに関する記述を改訂した。
  • 「第8章 プルリクエストしてみたい！」内の「8.2 プルリクエストのテーマは1つに絞ろう」において、別の変更に依存する変更の提案の仕方を追加した。
  • 「第11章 プルリクエストをマージしてもらえない！」内の「11.1 既存のコードをよく読もう」において、コーディングスタイルの解説を改訂した。
  • 「第13章 バグ報告やパッチ提供以外のコントリビュート」内の「13.2 Wikiの内容のメンテナンス」から、MDNへの言及を削除した（Wikiでなくなったため）。
  • 「第14章 ライセンスについてより正確に知る」内の「14.1 コードと著作権」において、GNU Emacsへのコントリビュートの著作権譲渡の注釈に公式ドキュメントのURLを追加した。
  • 「第14章 ライセンスについてより正確に知る」内の「14.2 オープンソースの定義って？」において、BSDライクライセンスの注釈に、BSDライセンスの各種バリエーションをBSDライセンスと同一と見なす考え方への言及を追加した。
  • 「第14章 ライセンスについてより正確に知る」内の「14.3 コピーレフト型のライセンスで気をつけること」において、組織内に限定して使用する場合のライセンスの取り扱いの説明を修正し、コラム「受託開発とGPL」を追加した。
  • 全体に渡って細かい表現を改めて、読みやすさを向上させた（つもり）。
  • v1.2からの全変更点
• v1.2：電子書籍2刷/商業版底本（2020年4月6日付）
  • 「はじめに」「おわりに」の内容を、最新のOSS Gateワークショップ開催状況に合わせて更新した。
  • 「第4章 どこにフィードバックしたらいいか分からない」内コラム「イシュートラッカーとは？」について、バグトラッキングシステムからイシュートラッキングシステムが生まれたという書き方になっていたのを、イシュートラッキングシステムの一形態がバグトラッキングシステムであるという書き方に改めた。
  • 「第5章 どう報告すればいいのか分からない」内にコラム「エラーの原因を探ってみよう」を追加した。
  • 「第10章 要望が通らない！」内コラム「理不尽な却下もあり得る、と心得ておこう」を、章末へ移動した。
  • 「第14章 ライセンスについてより正確に知る」内の「14.2 オープンソースの定義って？」において、オープンソースの定義の第7項に対する注釈が、誤って第4項に対する注釈になっていたのを修正した。
  • 「第14章 ライセンスについてより正確に知る」内の「14.2 オープンソースの定義って？」において、オープンソースの定義の第7項の説明が誤っていたのを修正した。
  • 全体に渡って、「という」の連続使用を減らしたり、文意がより分かりやすくなるよう表現を改めたりして、読みやすさを向上させた（つもり）。
  • 本文中で強調されたフレーズを、印刷時にも分かりやすいよう、明朝体の太字ではなくゴシック体で表示するようにした。
  • v1.1からの全変更点
  • v1.0からの全変更点
• v1.1：電子書籍初版（2020年2月29日付）
  • 「第9章 他の人のフィードバックから学ぼう」内の「9.2 画面上の表示に関わる問題の、より分かりやすい説明」のフィードバック例について、投稿者がインド在住の方である旨を追記した。
  • v1.0からの全変更点
• v1.0：紙媒体 初刷分（2020年2月29日付）

目次

• はじめに
• 第1部 フィードバックするための準備
  • 本当に「誰でもできる」の？
  • OSSを探そう
  • 何をフィードバックしたらいいのか分からない
  • どこにフィードバックしたらいいか分からない
• 第2部 最初のフィードバック
  • どう報告すればいいのか分からない
  • 英語での報告の仕方が分からない
  • それでもためらってしまうあなたへ
  • プルリクエストしてみたい
  • 他の人のフィードバックから学ぼう
• 第3部 フィードバックした後のこと
  • 要望が通らない！
  • プルリクエストをマージしてもらえない！
  • 仕事が忙しくてOSS活動に時間を割けない！
  • バグ報告やパッチ提供以外のコントリビュート
  • ライセンスについてより正確に知る
• おわりに

対象読者

• やりたいフィードバックがあるが、やり方が分からなくてためらっている人
• 特に具体的なフィードバックがある訳ではないが、好きなOSSがあってそれに関わりたいという人
• 功名心などの外的なモチベーションでOSSに関わりたいという人
• 作った物をOSSとして公開してみたい人→ライブラリなどのバグを踏む事があるので

執筆者向け情報

ページ数の概算

1ページあたり1400文字と仮定してページ数を概算するには、以下のようにする。

echo "scale=2; $(cat chapters/*.md | wc -m) / 1400" | bc

電子書籍用データ・印刷用データのビルド手順

Ubuntu 18.04LTS on WSL on Windows 10で動作を確認した。

必要なパッケージをインストールする。

$ sudo apt install texlive-binaries texlive-lang-japanese \
                   texlive-latex-recommended texlive-latex-extra \
                   imagemagick \
                   ruby-dev build-essential
$ sudo gem install bundler -v 2.3.26
$ sudo gem install unicode-display_width

npmのインストールも必要。 aptで入るバージョンは古いので、Ubuntuに最新のNode.jsを難なくインストールする - Qiitaなどで紹介されているように、nを使って最新安定版のnpmを使える状態にする。

PDFtkをインストールする。

$ sudo add-apt-repository ppa:malteworld/ppa
$ sudo apt update
$ sudo apt install pdftk

Re:VIEWをインストールする。リリース版（4.0.0）ではビルドに失敗したため、masterを使う。

$ git clone https://github.com/kmuto/review.git
$ cd review
$ bundle install --path vendor/bundle
$ rake build
$ sudo gem install pkg/review-*.gem
$ cd ..

easybooksをインストールする。リリース版ではビルドに失敗し、且つ、要件を満たさないため、改造版を使う。

$ git clone https://github.com/piroor/easybooks.git
$ cd easybooks
$ git checkout enhanced
$ npm install
$ npm run build
$ sudo npm install -g .
$ cd ..

以上で準備完了。makeするとPDFとEPUBの両方が作られ、distディレクトリ配下に出力される。

$ git clone https://github.com/oss-gate/first-feedback-guidebook.git
$ cd first-feedback-guidebook
$ make

印刷・製本

以下のファイルを使用する。

• 表紙： images/cover-full-outline.ai
• 本文： dist/first-feedback-guidebook-print.pdf

初刷分は日光企画にて以下の仕様で発注した。

• B5 196ページ（表紙込み）
• 表紙：NPホワイト200kg+マットPP
• 本文：上質90kg
• オフセット印刷 無線綴じ

個人用途などで1冊から製本したい場合、製本直送.comなどのサービスがある。 初刷分と同等の仕様の場合、2020年2月29日時点の見積もりでは送料込みで1327円だった。

ライセンス

全体のライセンスは、Wikipediaと同様とします。

• CC BY-SA 4.0
• GFDL

著作者のクレジットは以下のいずれか、またはその併記とします。

• OSS Gate
• 結城洋志（YUKI "Piro" Hiroshi）：以下のバリエーションも可
  • YUKI Hiroshi
  • Piro
  • Piro / YUKI Hiroshi
  • YUKI Hiroshi / Piro
  • Piro / 結城洋志
  • 結城洋志 / Piro

ただし、寄稿頂いた部分などは別のライセンスが設定される場合があります。