New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Railsガイドの「Rails をはじめよう」にある「8.4 コントローラを生成する」について #1550
Comments
@Angy-h ご報告ありがとうございます!スクリーンショットなどの画像系は更新し忘れがちで、今回の件も「実際の結果」が正しく、画像の方が古い状態のようですね 💦 cc/ @hachi8833 もしよければ画像と同じように、
といった情報を入力した上で、該当部分の画像を差し替えるプルリクエストを送ってもらえると嬉しいです (>人< )💖 なお rails/rails の方も同様に古いスクリーンショットを使っていることを確認できたため、 rails/rails に(英語で)プルリクエストを送ってみるとマージされる可能性もありそう です! (≧∇≦)b✨ https://edgeguides.rubyonrails.org/getting_started.html#generating-a-controller |
@yasulab お送りしました報告をご確認いただきまして、また、ご返信くださり、誠にありがとうございます。 |
@Angy-h さん、フィードバックありがとうございます! |
@Angy-h 念のためひとつ確認いただきたいのですが、このissueの冒頭に貼っていただいた「実際の画像」(図の右)は、以下のうちv6.0の手順に沿った場合の画像のようです。
私が最新のv7.1で再現したところ、以下の赤い囲みの部分はソースコードに含まれていませんでした。v6.1〜v7.1いずれも囲みの部分はソースコードに含まれていませんでした。 <!-- ガイドv6.0 -->
<p>
<strong>Title:</strong>
<%= @article.title %>
</p>
<p>
<strong>Text:</strong>
<%= @article.text %>
</p> <!-- ガイドv6.1 以降-->
<h1><%= @article.title %></h1>
<p><%= @article.body %></p> |
@hachi8833 お世話になります。 現況報告をさせていただきますと、ただ今、OSS GATEの作業用ログでご指導を受けてます。 |
@Angy-h oss-gate/workshop#1745 で https://github.com/rails/rails にプルリクエストを送るまでのサポートをするよりもここでやった方が今後同じような流れになった人(日本語版のRailsガイドを修正しようと思ったけど英語版を修正した方がよさそう!となった人)の役に立ちそうなので、続きはここでやりませんか!? @yasulab いいっすよね!? |
Railsガイド - Railsのドキュメントに貢献するによると英語版を修正する手順は以下の通り。
タスクに分けるとこうですね。
#1550 (comment) によるとプルリクエストを送ったことはないということなので、1.のやり方をブレイクダウンしないとできない。 では、GitHubの公式ドキュメント https://docs.github.com/ja/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request をベースにやってみましょうか! 上から読んで順番にやりましょう。まずはすごく先頭らへんにある↓の部分までやってみてください。(今回は「リポジトリへの書き込みアクセス許可がない場合」です。 https://github.com/rails/rails への書き込みアクセス許可がないからです。)
|
@kouさん、お疲れ様です。ご指導ありがとうございます。 |
@Angy-h そうっすね。大丈夫そうです。 では、そのパソコン内の ↑はGitを使える前提の説明なんですが、Gitを使った経験はありますか?ないならそこらへんから説明するので言ってください。 |
@kouさん、お世話になります。ご指南ありがとうございます。 1.「トピックブランチ」を作成する、について 2.必要な変更を行う、については、次の内容でよろしいでしょうか? 2-3 rails_en_forked/guides/images/getting_startedフォルダの中に、撮り直したイメージnew_article_with_comments.pngを保存する。 確認した事 *フォルダ内には、rails_en_forked/guides/sourceの中に、索引らしき名称がついているファイルがあることを確認しました。 長々といろいろすみません。 |
@hachi8833 さん、お心遣いありがとうございます。私が要領を得ないため時間がかかってしまい、ご心配をおかけしております。初心者の私にとっては、なかなかハードルの高い工程ですが、kouさんのご指導の下、できるところまで頑張ってみたいと思います。 |
そうっすね。それでもOKです。
私は何をするブランチかを端的に表す名前を使っています。たとえば、
私は使いませんが、 いろいろアプローチはありますが、何に注目したブランチかがわかる名前ならなんでもいいです。なので、"getting_started_8.4_image"も悪くないです。
これも既存のファイルを更新してください。
あっていると思うのですが、より確実に確認する場合は、リポジトリー内にあるファイルからHTMLを生成してみて期待した結果になっているかを確認するのがいいと思います。 https://railsguides.jp/contributing_to_ruby_on_rails.html#rails%E3%81%AE%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AB%E8%B2%A2%E7%8C%AE%E3%81%99%E3%82%8B 関連のドキュメントでHTMLを生成する方法が説明されていないか確認してもらえますか?説明されていなかったらここにいる誰かが助けてくれるはず!
はい、一緒に問題を解決していきましょう! |
お世話になっております。 1.rails_en_forkedフォルダーに移動して「トピックブランチ」:getting-started-update-screenshotを作成しました。 3.そのガイドの中で、最新のBundlerをインストールするようにとありましたので、インストールしました。 4.その次に、そのガイドの中にあります、$ bundle exec rake guides:generateや$ bundle exec rake guides:generate:htmlを行ったところ、bundle installを先に行うようにというメッセージが出てきました。 5.そのため、bundle installを行ったところ、インストールが始まり、下記のような結果になりました。 6.その後、$ bundle exec rake guides:generateや$ bundle exec rake guides:generate:htmlを行いましたが、次のような結果となりました。 |
実行結果を共有するのはすごくいい進め方なので継続してください!
とかしてそのまま書いてもらった方が助かります。テキストだけページ内検索をできますが、スクリーンショットだとできないからです。 ページのレンダリング結果とかテキスト以外の情報も含むときはスクリーンショットの方がいいです! https://railsguides.jp/ruby_on_rails_guides_guidelines.html#html%E3%82%AC%E3%82%A4%E3%83%89 には
とありますが、「cdコマンドでguidesディレクトリに移動し」をやっていないように見えます。 「bundle installを実行してから」の部分も見逃していたようですし、実行しなければいけないコマンドは本文で説明するよりも これは、別に見逃したことが悪いと言っているわけではなくて、「初めての人が普通にやってみたら見逃したという事実がある」と言っているに過ぎません。そして、このドキュメントは「初めての人が普通にやったら普通にできる」ことを意図した文書のはずなので、既存のドキュメントに改良する余地がありそうということがわかったということです。 このスクリーンショットの更新が一段落したら、このあたりの書き方の改良を提案する、ということにもチャレンジしてもいいかもしれません。 |
お世話になります! 8までの作業を行いました。
ターミナルで下記を実行する。
これは、getting-started-update-screenshotにいる状態で実行するということでよろしいでしょうか? 行った作業
2.最新のBunderが使用されていることを確認
3.cdコマンドでguidesディレクトリに移動し、bundle installを実行
4.下記を実行 5.HTMLが作成されたので(やったー!)、getting_started.htmlページでイメージのファイル名を確認 6.guides/assets/images/getting_startedのフォルダへ作成した画像をarticle_with_comments.pngという名前で保存(差し替え) 8.git diffで確認
|
今年もよろしくお願いします!
guides$ git add assets/images/getting_started/article_with_comments.png
guides$ git commit -m "Update screenshot in Getting Started"
guides$ git push origin getting-started-update-screenshot |
お世話になります。 早速、下記コマンドを実行しました。
2つ目までは進みましたが、3つ目を実行すると、下記のエラーが出てきました。
ChatGPTに聞いてみると、
次に、リモートの origin に getting-started-update-screenshot ブランチが存在するかどうかも確認する必要がある、ということでしたので、
そうすると、ChatGPTは、この出力から、getting-started-update-screenshot ブランチがリモートの origin には存在しない、ということなので、下記を実行してみてください、ということでした。
3つ目のコマンド なんだか一向に前に進まなくて大変恐縮です。 |
あれ、
最初はみんなそんなものなのでくじけずに一歩ずつ進んでいきましょう! |
お世話になります。
ターミナルの実行結果
|
嘘です。ChatGPTにだまされないでください!
|
あと、 |
ご返信ありがとうございます。
|
うーん、ブランチ名の前に全角スペースが入っている気がしますね。。。 $ git branch -m ' getting-started-update-screenshot' getting-started-update-screenshot
$ git push origin getting-started-update-screenshot |
大変失礼いたしました。
フォークしたリモートリポジトリ(?)の方も次のようになっていました! 次は、プルリクエストの作成に進むとよろしいでしょうか? |
そうっすね。 #1550 (comment) で確認した通り、プルリクエストのタイトルには あと、プルリクエストを作るときはタイトルだけではなく本文も書く必要があるので、まずは、タイトルと本文の内容をここで考えて、できあがってからプルリクエストを作りましょう。 https://raw.githubusercontent.com/rails/rails/main/.github/pull_request_template.md にプルリクエストの本文のテンプレートがあるので、これをベースに作ってみてください。どう書けばいいかわからないところはどうしてどう書けばいいかわからなかったかを教えてください。このテンプレートの改善が必要かもしれません。 |
https://github.com/rails/rails/commits/main/guides がコミット履歴ですが、対応するプルリクエストへのリンクがあるものもあるので、そういう既存のプルリクエストでの書き方も参考にしてみてください。 |
いつもご指導ありがとうございます! 作成にあたっては、次の点をご報告と質問をさせていただきます。
タイトルと本文の下書きは、次のとおりです。 タイトル:Update the screenshot in the section 8.4 of Getting Started with Rails [ci skip] Motivation / BackgroundI've been following the RAILS GUIDES available at https://railsguides.jp/getting_started.html in Japanese (https://edgeguides.rubyonrails.org/getting_started.html in English). Upon reaching the end of section 8.4, I noticed several differences between the output displayed in the guide's screenshot and what appeared on my computer:
DetailThis Pull Request changes article_with_comments.png in /guides/assets/images/getting_started. ChecklistBefore submitting the PR make sure the following are checked:
|
そうっすね。
そうですね。いらないです。
チェックをつけていいです。というか、つけます。
Gitのコミットメッセージでは3行目以降に書かれるやつの部分になります。 @yasulab @hachi8833 Gitのコミットメッセージのお作法(1行目はタイトルで2行目は空行にしてとか)をいい感じに説明したWebページを知っていたら共有してもらえますか? 今回の場合だと「今のスクリーンショットは古いRailsで動かしたときに撮ったもののようなのでRails Xだと違う結果になる。だから、Rails Xでスクリーンショットを撮り直したよ。」くらい書くのがdetailedな話になります。今回は「Getting Startedのスクリーンショットを更新したよ」しか書いていないのでdetailedではないですね。たとえば、今回はRailsのどのバージョンかが大事なポイントになると思いますが、そういうのが入っていません。
異なることを言っているわけではないですね。大事なところはwhat changedとwhyのdetailed descriptionがあるかないかです。最初の文はコミットメッセージにある?ことに注目していて、次の文はコミットメッセージにないなら関連issueには書いてあるか?に注目しています。どちらも、 what changedとwhyのdetailed descriptionがあることを気にしています。 今回の場合、detailedではないですがwhatは入っている(スクリーンショットを更新した)んですが、whyはまったく入っていないのでチェックはつきません。なので、チェックをつけられるようなコミットメッセージにしないといけません。
これは実装に関する変更のことなはずなのでチェック無しでいいです。
documentation changesになるのでCHANGELOGは更新しません。よってチェック無しでいいです。
コミットメッセージをdetaild descriptionにして(what changedとwhyは必ず入れる)、その情報も追加したら大丈夫な気がします! コミット済みのコミットのメッセージは @yasulab @hachi8833 |
@kou お疲れさまです🙏!こちらでも取り急ぎ見繕ってみました: コミットメッセージのお作法:
|
書こうとしたら hachi8833 さんが書いてくれた...!! ありがとうございます!! 🙏 ✨ |
あざっす! |
皆さま、ご指導ありがとうございます! コミットメッセージを修正する内容を考えました。
コミットメッセージの修正 タイトルと本文の下書きも修正しました。
タイトル:Update the screenshot in the section 8.4 of Getting Started with Rails [ci skip] Motivation / BackgroundI've been following the RAILS GUIDES available at https://railsguides.jp/getting_started.html in Japanese (https://edgeguides.rubyonrails.org/getting_started.html in English). Upon reaching the end of section 8.4, I noticed several differences between the output displayed in the guide's screenshot and what appeared on my computer (rails version: Rails 7.1.2, ruby version: ruby 3.2.2):
I would like to update the existing screenshot. DetailThis Pull Request changes article_with_comments.png in /guides/assets/images/getting_started. ChecklistBefore submitting the PR make sure the following are checked:
|
@Angy-h コミットメッセージ良さそうです!😆👌✨ 個人的な所感としては Description が比較的重要かなと思うので、自分の場合は Description を気にすることが多いですね 👀 ✅ で、以下の部分についてですが、
自分なら、議論の的を絞るために Translation 関連の話はせず、より簡潔に以下のように書きますね! (確認する工程で英語版でも確かめていただいているかなと思うので) - I've been following the RAILS GUIDES available at https://railsguides.jp/getting_started.html in Japanese (https://edgeguides.rubyonrails.org/getting_started.html in English). Upon reaching ...
+ I've been following the [getting started guide](https://edgeguides.rubyonrails.org/getting_started.html). Upon reaching ... Railsガイド運営者視点では Japanese に触れていただけると存在感が高まって嬉しい限りですが、一方で PR の Description に Japanese/English の話を混ぜ込むと、Review する人から見て「それ Japanese だからでは? English なら大丈夫では?」と返されてマージされない可能性もありそうです。なので(もちろん英語版でも事前に確認した上で)上記のように的を絞った文にしておくと、不要なリスクを負わずに済みそうかなと思いました! (๑•̀ㅂ•́)و✨ ご参考になれば幸いです...!! (>人< )✨ |
@yasulabさん、アドバイスありがとうございます。 タイトルと本文の下書きを次のように修正いたします。
Motivation / BackgroundI've been following the getting started guide. Upon reaching the end of section 8.4, I noticed several differences between the output displayed in the guide's screenshot and what appeared on my computer (rails version: Rails 7.1.2, ruby version: ruby 3.2.2):
I would like to update the existing screenshot. DetailThis Pull Request changes article_with_comments.png in /guides/assets/images/getting_started. ChecklistBefore submitting the PR make sure the following are checked:
|
良さそうです...!! (๑•̀ㅂ•́)و✨ 準備できたらPR送ってみても良いかもですね 😆👌✨ |
ありがとうございます! |
たしかに
いいです。
ないです! pushしたらpull requestにしちゃいましょうか! |
いつもお世話になっております。 コミットメッセージの修正の方、実行いたしました。
エラーは出ていないので、できているように思います。
プルリクエストの方、作成してみました。 下記のドキュメントで説明されている黄色のバナー(Compare & pull request)が表示されていませんでした。 下記のページを参照して作成しました。 |
コミットメッセージは80文字くらいで折り返したほうがいいです。なので、
は
とかの方がベターです。
ブランチが作られた直後なら黄色のバナーが出るんですが、しばらくするとでなくなるんです。 |
クリックしてください!
|
ご確認ありがとうございます! 上記を見直しますと、確かに |
rails/rails#50756 っすね! |
はい!その通りです! |
@Angy-h 無事にマージされましたね!! おめでとうございます...!!! 🥳🎉✨ もしよければ本リポジトリ(Railsガイド)の方にも同じ内容でプルリクを送っていただけると嬉しいです...!! cc/ @hachi8833 (コチラは日本語のDescriptionで大丈夫です!) |
ありがとうございます!無事にマージされてとても嬉しいです。 日本語のrailsガイド方にもスクリーンショットのプルリクエストをお送りすることになっていること、承知いたしました。 一つお伺いさせていただければと思います。
この中の「関連しているので。」の「。」は、「、」ではないかな?と気になっています。 |
@Angy-h 句読点の部分はミスっぽいですね! 😂 まとめて送っていただいても別々に送っていただいても、どちらでも大丈夫です...!! 🆗✨ (やりやすい方で 😆👌) |
やりましたね! 今回のようにメンテナンスしている人からまとめてでいいよーと言ってもらっている場合はまとめてでもいいんですが、一般的には、論理的に分離できる変更は別々に送るのがいいです。別々に送ると、それぞれでよさそうねとなった段階で個別にマージしていけますが、まとめて送ると、一部の変更がネックになった場合に、変更全体がマージできないからです。 |
はい!先ほど勇気を出して英語のrailsガイドの該当箇所を見てきましたところ、新しい画像に更新されていました! 日本語のrailsガイドの方、プルリクエストを送れるように教えていただいた手順を見直して進めます。 |
本件について英語版のRails Guides含め、ご対応いただきありがとうございました!👏✨ 本 Issue のタイトルにある件については以下のプルリクエストで対応されましたので、本 Issue は Close しますね。改めて、対応ありがとうございました...!! 🙏 💖 |
ご丁寧にご連絡くださりありがとうございます。 |
Railsガイドを利用して、学習させていただいています。いつもありがとうございます。
フィードバック
Edid | Backのリンクを付けるための手順の記載がないようでした。
示されている成果物と同じ結果にならないようでしたので、ご報告させていただきます。
再現方法
RailガイドのRails をはじめようの8.4 コントローラを生成する」のパートの内容を手順通りに進めました。
The text was updated successfully, but these errors were encountered: