数字で見る Indeed + Hacktoberfest 2020

Indeed + Hacktoberfest 2020の結果が出ましたので、皆さんに共有します。

対外的な取り組み 社内での取り組み
Indeed は、Hacktoberfest Community Partnerとして社外のコミュニティと直接のつながりを構築しました。

Indeed 社内のコントリビューターの基盤を築くため、柔軟性を重視しました。

  • 4つのタイムゾーンでバーチャルスタディホールを開催した数:29回
  • 毎週参加したオープンソースアンバサダーの数:11人
  • オープンソースプロジェクトへの初参加者数:65人
  • Hacktoberfestへの参加者数:100人
  • アクティビティ数(プルリクエストの作成、イシューの登録、コメントの投稿、およびコードレビュー):2,229件
  • 送られたプルリクエストの数:328件

Ocean diver representing our oceanic ecosystemIndeed が大切にしているのはオープンソースのサステナビリティです。その意味について、海の生態系に例えて考えてみましょう。

海にはきれいな水、ありとあらゆる大きさの魚、魚が集まるサンゴ礁、環境をきれいにする生物、そして大きな生き物の餌となるプランクトンが存在します。海の世界と同じように、私たちのオープンソースのエコシステムも多様であり、互いにつながることで成り立っています。Indeed では、あらゆる規模のプロジェクトをサポートし、コントリビューターが集まるイベントを企画し、クリーンアップなどの環境整備を行い、プロジェクトの発展を支援しています。こうしたマインドフルなアプローチによって、オープンソースを活用する人とコントリビューターが、共にメリットを得られるようなオープンソースプロジェクトの実施を支援することを目指しています。

9月は準備の月(Prep-tember)

9月はHacktoberfestの準備で非常に忙しい月でした。Indeed のOpen Source Program Office(OSPO)は、私たちが企業として取り組み、Hacktoberfest期間中にPRするべき6件のプロジェクトを決定しました。選定にあたっては、Indeed が積極的に活用しているプロジェクトであることと、プロジェクトのメンテナーのうち少なくとも1人が Indeed の従業員であることを基準にしました。

Indeed のプログラムオフィスはプロジェクトのメンテナーとHacktoberfestのガイドラインを共有しました。メンテナーに担当プロジェクトでサポートが必要なリポジトリとイシューにタグを付けるよう依頼するとともに、コメントやプルリクエスト(PR)のマージ依頼への対応は3日以内に実施することとしました。その上で、メンテナーと協力し、オープンオフィスアワーのスケジュールの設定と発表を行いました。マネージャーのサポートは極めて重要であるため、メンテナーやそのマネージャーと話し合って、就業時間中にHacktoberfestの取り組みに時間を充てられるようにしました。

社外のコミュニティとつながる

オフィスアワーの開催とタイムリーなPRのマージによって、Hacktoberfest参加者の経験をポジティブなものにすることができました。

メンテナーは複数の枠のオフィスアワーを設定しました。オフィスアワーには、Indeed の従業員であるかどうかを問わず、誰もがビデオ会議に参加でき、プロジェクトについて質問するいい機会となりました。また、プログラムオフィスが働きかけ、Indeed のHacktoberfest用のランディングページであるHacktoberfest Event Boardや各プロジェクトのreadme.mdページ上でもPR活動が実施されました。

社内でのリーチを広げる

バーチャルスタディホール(プロジェクト用ではない社内のオフィスアワー)では多くの従業員にサポートを提供することができました。開催日時を固定せず、必要に応じてプログラムオフィスとオープンソースアンバサダーが開催する方法をとり、10月には毎日複数回のスタディホールを開催しました。

また、新たにメンターシッププログラムを開始し、メンターとメンティーの両方を募集しました。まったくの未経験者や、イシューを見つけるための助けが必要な人、技術的なスキルを向上するために「リーチ」イシューをクローズするためのアドバイスを求めている人など参加者のレベルはさまざまなので、タイムゾーンやオープンソースについての経験を考慮して、メンターとメンティーのペアを作りました。

スタディホールとメンターシッププログラムが素晴らしかった。熱意のあるコミュニティで、Hacktoberfestの期間中、手厚いサポートを受け、やる気を引き出してもらったと感じた。 — Technical Business Analyst

Indeed のオープンソースプロジェクトを活用する

Hacktoberfestでは、Indeed が依存しているプロジェクトの未解決のイシューについて、既存のツールを実例として共有しました。まず、Mariner(2019年に Indeed のOSPOがオープンソース化)を使い、オープンソースプロジェクトで最近作成された初心者向きのイシューを特定しました。2020年には、MarinerのうちGitHub Actionとして作動するバージョンであるMariner Issue Collectorをオープンソース化しました。2019年8月以降、Indeed ではMarinerのアウトプットを使って Indeed の従業員にコントリビューションの機会を紹介する社内ブログを毎週投稿しています。

また、Starfish(2019年にプログラムオフィスがオープンソース化)を利用してHacktoberfestに参加した従業員のリストを作成しました。Starfishを使用したのは、GitHub IDの付与日に関わらず、一定期間内のコントリビューションを正確に示してくれるためです。また、Indeed のFOSS Contributor Fundで投票する資格のある従業員のリストもStarfishで作成しています。

オープンソースのサステナビリティを促進する

このようにHacktoberfest 2020では満足のいく大きな成果を上げることができました。Indeed では、オープンソースプロジェクトを活用し、貢献することを習慣として継続することによってのみ、オープンソースのサステナビリティの目標を達成できると考えています。Hacktoberfestのようなイベントは、毎日使っているオープンソースソフトウェアをサポートする取り組みに、Indeed 従業員が参加するきっかけとなったり、やる気を後押しするものでもあります。四半期中に2日以上オープンソースに貢献した人の人数をプログラムの成果測定の1つとして使っており、社内では、この指標を「Active Recurring Participants(ARP)」と呼んでいます。10月は、前四半期と比較した場合のARPが、200%以上増加しました。

正直に言うと、OSS(オープンソース)に参加することを目標として以来、何年もの時間が経ってしまっていたが、今週で私のPRは0から5になった。オープンソースにコミットするきっかけを作ってくれたこと、サポートしてくれたことに感謝している。— Senior Quality Assurance Automation Engineer

Hacktoberfest 2020での取り組みを通じて生まれたパワーを活かし、私たちは引き続き Indeed が依存している未解決のイシューを投稿していきます。また、Indeed 従業員がそれぞれのやり方で参加できるよう、Hacktoberfestに参加した従業員100人を対象としてアンケートも実施しました。

私たちは、オープンソースへの貢献を始めるのに最も良いタイミングは今だと考えています。そして、最良のオープンソースのエコシステムはサステナブルであるという信念を持っています。

k8dash: Indeed’s Open Source Kubernetes Dashboard

So you’ve got your first Kubernetes (also known as k8s) cluster up and running. Congratulations! Now, how do you operate the thing? Deployments, replica sets, stateful sets, pods, ingress, oh my! Getting Kubernetes running can feel like a big enough challenge in and of itself, but does day two of operations need to be just as much of a challenge?

Kubernetes is an amazing but complex system. The learning curve can be steep. Plus, the standard Kubernetes dashboard has limited features. Another option is kubectl, which is extremely powerful but also a power user tool. Even if you become a kubectl wizard, can you expect everyone in your organization to do the same? And with kubectl it’s difficult to gain visibility into the general health and performance of the entire cluster all at once.

Enter k8dash—pronounced Kate Dash (/kāt,daSH/)—Indeed’s open source Kubernetes dashboard.

k8dash dashboard

Since k8dash’s release in March of 2019, it’s received over 625 Github stars and been downloaded from DockerHub over 1 million times. k8dash is a key component of Kubernetes operations for many organizations.

In May of 2020, the Indeed Engineering organization adopted the k8dash project. We’re excited about the visibility this brings to the project.

Benefits of managing your Kubernetes cluster with k8dash

Here are a few of the benefits of k8dash. See more of k8dash in action here.

Quick installation

Low operational complexity is a core tenet of the k8dash project. As such, you can install k8dash quickly with a couple dozen lines of YAML. k8dash runs only a single service. No databases or caches are required. This extends to AuthN/AuthZ via OIDC. If you’re already using OIDC to secure your cluster, k8dash makes extending this to your dashboards easy: configure 2-3 environment variables and you’re up and running. No special authenticating proxies or other complicated configurations are required.

Cluster visualization and management

k8dash helps you understand the current status of all of your cluster’s moving parts: namespaces, nodes, pods, deployments. Real-time charts show poorly performing resources. The intuitive interface removes much of the behind-the-scenes complexity and helps flatten your Kubernetes learning curve.

You can manage your cluster components via the dashboard and leverage k8dash’s YAML editor to edit resources. k8dash uses the Kubernetes API and provides context-aware API docs. With k8dash you can view pod logs and even SSH directly into a running pod via a terminal directly in your browser, with a single click.

k8dash also integrates with Metrics Server, letting you visualize CPU/RAM usage. This visualization helps you understand how well your services are running. As Kubernetes simplifies the complexity of running hundreds or even thousands of microservices across an abstract compute pool, it brings the promise of improved resource utilization through bin packing. However, for many organizations this promise goes unrealized because it can be difficult to know which services are over- or under-provisioned. k8dash’s intuitive UI takes the guesswork out of understanding how well services are provisioned.

Real-time dashboard

Because k8dash is a real-time dashboard, you don’t need to refresh pages to see the current state of your cluster. Instead, you can watch charts, graphs, and tables update in real time as you roll out a deployment. You can watch as nodes are added to and removed from your cluster, and know as soon as new nodes are fully available. Or, simply monitor a stream of Kubernetes cluster-wide events as they happen.

Because k8dash is mobile optimized, you can monitor—and even modify—your cluster on the go. If you’re getting paged about a troublesome pod just as your movie is about to start, with k8dash you can restart the pod directly from your phone!

The k8dash project: How to contribute

k8dash is made up of a lightweight server and a client, and we’re always looking for core contributors.

The server—built in Node.js and weighing in at ~150 LOC—is predominantly a proxy for the front end to the Kubernetes API server. The k8dash server makes heavy use of the following npm packages:

  • express (web server)
  • http-proxy-middleware (proxies requests to Kubernetes API)
  • @kubernetes/client-node (official Kubernetes npm module. Used to discover Kubernetes API location)
  • openid-client (fantastic npm module for OIDC)

The client is a React.js application (using create-react-app) with minimal additional dependencies.

If you would like to contribute, see the list of issues in GitHub.


About the author

Eric Herbrandson is a staff software engineer and member of the site reliability engineering team at Indeed. Eric has used orchestration frameworks, including ECS, Heroku, Docker Swarm, Hashicorp’s Nomad, DCOS (Marathon/Mesos), and Kubernetes. While finding Kubernetes to be the clear winner in the orchestration space, Eric recognized that existing visualization options were lacking compared to other frameworks. In an effort to better understand the Kubernetes API and to create a solution that contained all of the features he needed, Eric developed k8dash over a three-week period.

Cross-posted on Medium.

Jackson:ユーザー基盤が拡大したことによる新たな課題

Jacksonは、完成度の高い多機能なオープンソースプロジェクトで、Indeed でも利用やサポート、コントリビュートを行っています。私の前回の投稿では、Java用のJSONライブラリとしての主力機能を紹介しました。また、Jacksonがサポートするその他のデータフォーマット、データ型、JVM言語についても説明しました。今回は、Jacksonの作成者と主任メンテナーを務める私の視点から、Jacksonの拡大に伴う課題についてお伝えします。また、このような課題にコミュニティとして対処するためのプランについても紹介します。

A running river surrounded by lush tress in Cape Flattery in Washington.

フラッタリー岬の反対側(撮影:Tatu Saloranta)

成長の痛み

Jacksonプロジェクトには、大規模なコントリビューターのコミュニティのサポートを得て、13年の間に多くの新機能が加わってきました。ユーザーはイシューを報告し、デベロッパーは修正や新機能に加え、新しいモジュールの提供も行っています。たとえば、Java 8の日付と時刻データ型モジュールはJSR-310で指定されているJava 8の日付と時刻型、java.time.*をサポートするもので、仕様そのものと並行してコミュニティのメンバーが開発しました。

これまでにないほどの機能やユーザー基盤の拡大は、Jacksonに成長の痛みをもたらしており、以下のような支援が必要になっています。

  • ドキュメンテーションの改善
  • プロジェクトのWebサイトの改良とブランディング
  • 大規模な変更や機能の管理と優先順位決め
  • 報告されたイシューの詳細の絞り込み
  • Jacksonに依存している機能に対するJacksonの新バージョンの互換性テスト

ドキュメンテーションの構造と編成

ドキュメンテーションを十分に提供し、アクセシビリティや内容の新しさを維持することは、広範囲で利用されているライブラリやフレームワークにとっては常に課題となります。Jacksonも例外ではなく、ドキュメンテーションの負担は、同程度のユーザー基盤を持つ他のライブラリよりも大きいかもしれません。

とはいえ、ドキュメンテーションが不足していることそのものが問題の本質ではなく、 Jacksonには、すでに次のような大量のコンテンツが存在します。

サードパーティ提供のチュートリアル
Jacksonプロジェクトリポジトリ
  • メインのJackson GitHubポータル
  • Jackson-docs GitHubリポジトリ
  • 個々のコンテンツリポジトリのREADMEと、特にjackson-databindに関するwikiページ
  • javadocによって生成された完全なAPIリファレンスがコンポーネントリポジトリに含まれている
StackOverflow

Jacksonには、関係のあるほとんどのクラスを記載したJavadocリファレンスも用意されていますが、巨大なライブラリなので、Javadocリファレンスは膨大すぎて新しいユーザーには使いにくいと感じられるようです。また、Javadocリファレンスには使用例も含まれていません。

私たちの最優先事項は、ライブラリの利用者に、以下に挙げるような最も一般的なユースケースを紹介する実践ガイドを作成することです。

  • JSON構造をJavaオブジェクトに対応するように変換する方法。
  • XMLなど、他のデータ型のフォーマットを作成する方法。
  • Spring/Spring Boot、DropWizard、JAX-RS/Jersey、Lombok、Immutablesなどのフレームワーク内でJacksonを使用する方法。

Javadocリファレンスの改善も必要です。一部のクラスやメソッドには説明がなく、説明があっても不完全な場合があります。自動生成されたJavadocリファレンスの他に、最もよく使われる機能やオブジェクトを詳しく説明するwikiページを私たちが手作業で作成し、公開しています。これらのwikiページを自動更新する方法を見つけたいと考えています。

これらのページの変更を実装するには、以下のドキュメンテーション構造、ツール、プロセスの変更が必要です。

  • インラインコンテンツと外部コンテンツへのリンクを追加するための上位構造
  • コントリビューターがドキュメンテーションを追加したり訂正したりするためのアクセス許可
  • 改良とメンテナンスの作業に集中するために役立つ、ドキュメンテーションのフィードバックメカニズム
  • 情報の追加を簡単にするドキュメンテーションテンプレート

プロジェクトのWebサイトとブランディング

このプロジェクトは13年の歴史があり、幅広く利用されていますが、メインプロジェクトのホームページの見た目はいまだに標準的なGitHubプロジェクトのままです。このリポジトリにはJacksonについての役に立つ情報がたくさん入っているにも関わらず、際立ったスタイルやブランド、ロゴがありません。

Hacktoberfest 2020では、Jacksonロゴデザインに関するイシューを作成しました。イメージしているのは、以下のようなロゴです。

大規模な変更の管理

多くのコードのコントリビューションがあることに感謝しています。そのほとんどは報告されたイシューの修正目的ですが、新機能のコードもあります。

これまでの経験から言えば、Jacksonプロジェクトのコントリビューションの中で特に価値があるのは、GitHubイシューとして登録されるユーザーバグレポートでしょう。毎週かなりの数のイシューを受け取り、修正や品質向上を行っています。このようなレポートがなければ、Jacksonがこれほどの品質を維持することはできなかったでしょう。また、新機能のリクエストもよく受け取りますが、これらも改善に役立つ貴重な意見であり、私たちが取り組むべき新規開発の優先順位付けにも役立っています。

大規模な変更や機能の管理については、さらに改善の余地があると考えています。このような取り組みは実行に時間がかかるため、慎重な計画やコラボレーションを通じて改善するのが効果的です。大規模な変更を1つのイシューとして処理することもできますが、扱いが難しくなってしまうこともあります。

Jacksonプロジェクトが助けを必要としているのは、新機能リクエストの優先順位を決めることです。

  • どの問題の改善を優先するべきなのか?
  • 活発で発言力が大きい少数の参加者に依存するのではなく、コミュニティ全体の総意をくみ取ることができるか?これは、不満の声が大きい問題ばかりが優先される状態になるのを防ぐのに大切なことです。
  • APIや実装計画について早めにフィードバックをもらうにはどうするのが最善か?既存のメーリングリスト、イシュートラッカー、チャットのどれを使ったとしても、それぞれに問題があります。

コミュニティからのフィードバックを促進していきたいという課題を解決するために、JSTEP(Jackson Strategic Enhancement Proposals)と名付けた、「小さな仕様」を公開するアイデアを取り入れました。KafkaのKIPと同じく、JSTEPの目的はコラボレーションの活性化です。GitHubのwikiページには、GitHubのイシューやGoogleドキュメントにあるような機能が備わっておらず、このようなツール上の制約から、今のところ一定のレベルの成果しか得られていません。

さらに、個人用と公開用を兼ねて、To DoやWork In Progress(WIP:進行中の作業)を記録したリストJackson WIPをGitHub wikiページで管理することを始めました。メンテナンスに手間をかけずに、自分の短期的なプランを記録し、共有するための仕組みです。

報告されたイシューを絞り込むためのコラボレーション

上で述べたように、これまでで最も役に立つタイプのフィードバックはバグレポートですが、役に立つ一方で、報告されたイシューと新機能リクエストの管理にはかなりの労力が求められます。データフォーマット、データ型、JVM言語、ユーザー基盤が拡大した今となっては、この管理が特に厳しくなってきました。

基本的なイシューのトリアージに時間がかかるようになり、以下のような手順が必要になっています。

  • 報告されたイシューを検証する。
  • 報告されたイシューが、ドキュメンテーションの不備や不明確な記述によるものかどうか判断する。
  • 質問して詳細を確認する。

機能とドキュメンテーションに取り組むための限られた時間から、このトリアージに対応する時間も捻出しなければなりません。また、イシューレポートの回答遅延は、報告者の満足度の低下にもつながります。

そこで希望者をトレーニングして、ボランティアとしてイシューのトリアージをサポートしてもらう方法を模索したいと思っています。以下に挙げたようなサポートで、イシューの素早い絞り込みとユーザーエンゲージメントの改善を実現することができます。

  • ラベルを追加する
  • 質問して詳細を確認する
  • 自分でも調査して発見事項を追加する
  • 必要に応じてモジュールや専門分野のエキスパートの協力を得る

jackson-databindのイシューを手始めに、以下のものを作成することによってワークフローを改善し、GitHubイシューの絞り込みを行いました。

  • ユーザーによるレポーティングの品質を向上するためのイシューテンプレート
  • 新規イシューに対して自動的に設定される「to-evaluate」ラベル
  • メーリングリストで頻出したり、同意を意味するサムズアップアイコンがGitHubで多く押されたイシューであることを示す「most-wanted」ラベル

これらの変更が成功すれば、他のプロジェクトリポジトリにも展開していきます。同じようなやり方で、他の変更も段階的に進めることができるでしょう。

依存関係がある機能に対する新バージョンの互換性テスト

Jacksonプロジェクトでは、コードのかなり広い部分でユニットテストを行っており、コアコンポーネントのカバレッジも良好です。さらにjackson-integration-testsリポジトリでは、コンポーネント間の機能テストを拡充する取り組みも始まったばかりです。一方、開発中のJacksonのマイナーバージョンと、Jacksonに依存する機能(たとえば、Spring Bootのようなフレームワーク)との互換性テストは、現在のところかなり後れを取っています。

課題の1つは、Jacksonとライブラリの開発ライフサイクルと、Jacksonを使用するフレームワークの開発ライフサイクルに差があることです。既存のライブラリとフレームワークは、安定したJacksonのマイナーバージョンに依存していて、すべてのテストがそのバージョンのみを対象に行われます。バージョン2.11が現在の安定バージョンです。イシューが見つかれば報告され、修正する場合は、2.11.1などのパッチリリースで行います。

同時に、Jacksonプロジェクトは新しいマイナーバージョン2.12の開発中で、これはバージョン2.12.0としてリリース、公開される予定です。バージョン2.11.1と2.12の作業が同時進行していることは問題ありません。Jacksonの公開APIでは標準のセマンティックバージョニング方式を使用していて、これが新しい問題の発生を防いでくれるはずです。

ところが現実には、標準のセマンティックバージョニングによって実際の問題をすべて防ぐことはできません。セマンティックバージョニングはJacksonの公開APIに使用されていますが、コアコンポーネント間の内部APIは同じレベルの後方互換性を備えていません。Jacksonのメンテナーが考慮するのは公開および文書化されたAPI間の互換性ですが、ユーザーはAPIの本来意図された動作よりも、実際の目に見える動作に頼りがちです。たとえば、メンテナーがバグや予期しない動作であると考えているものについて、ユーザー側では、それが実際の機能であったり正しい動作であるととらえていることがあります。

このような状況でも、開発中のJacksonのSNAPSHOTバージョンを使用してダウンストリームのシステムをテストすれば、新バージョンの開発サイクル中にこうした問題を把握して解決できます。この記事の執筆時点で提供されているSpring Bootの現行バージョンは、Jackson 2.11.2(最新パッチバージョン)に依存していますが、代わりにJackson 2.12.0-SNAPSHOTに依存するSpring Bootのユニットテストと統合テストを作成できます。スナップショットバージョンは定期的に公開され、Jacksonプロジェクトはスナップショットビルドを自動的に提供します。

このようなプロジェクト間の統合テストを行えば、関係するすべてのプロジェクトにとって有益です。リリースの前にリグレッションの一部、あるいは大部分の問題を予防することができ、パッチバージョンを作成する必要性が減ります。また、長い目で見ればJacksonのバージョン間の互換性が大幅に向上し、APIの意図された動作と実際の動作のギャップも埋まるはずです。

参加するには

Jacksonのユーザー基盤の拡大に伴って、ドキュメンテーション、ブランディング、イシューのトリアージ、イシューの優先順位決め、コードのテストなどの課題が生じています。この記事では、これらの課題に対処するために私たちが行ってきた取り組みのいくつかを紹介しました。これらの解決策を実装したり、代替策を提案してくださることが、私たちへの支援になります。Jacksonの将来の成長に向けて、一緒に土台を築き上げませんか?コントリビューションの機会については、Jackson Hacktoberfest 2020をご覧ください。詳しい情報については、Gitterチャットに参加するか、jackson-devメーリングリストに登録してください。


筆者紹介

Tatu Salorantaは、Indeed のスタッフソフトウェアエンジニアで、次世代の継続的デプロイメントシステムを統合するチームを率いています。Indeed の社外では、オープンソース分野での活動で広く知られる存在であり、@cowtowncoderのハンドルで、Jackson、Woodstox、lzf圧縮コーデック、Java ClassMateなど、多くの人気のあるオープンソースJavaライブラリを生み出しています。詳しい一覧についてはFasterXML Orgをご覧ください。