ホーム ›

バグ報告ガイドライン

バグ報告が効果的であるほど、修正される可能性も高い。このページではそのようなバグ報告の仕方を説明する。

事前準備

  • 最新版を使う。
  • github issues を検索して、バグがすでに報告されていないかどうか確認する。
  • 報告一件につき、バグ一つ。
  • 次のステップへ進む。

どこに報告するか

  • scalaxb を使ってて問題に遭遇した場合は、github issues にて英語で報告するか、公開しても構わないことを明記して日本語で (eed3si9n at gmail) 宛にメールを送る。
  • より一般的な質問や、新しいアイディアがある場合は、Google Group に英語で投稿するか、日本語でメールを送る。
  • もし、一般に公開できない問題があれば、その旨を明記した上でメールを送る。

Google Group は、scalaxb に関する一般的な議論や公式発表を目的とする。

いきなりバグ扱いするよりも、プログラム側に非がない場合を考えて、一般的な「質問」という形でバグ報告した方がいいんじゃないかと考えるかもしれない。心配ご無用。無効なバグ報告に腹を立てるようなことはないので、安心して報告してほしい。

バグの報告の仕方

開発者は、特に三つの情報を必要とする: 手順 (steps)、問題 (problem)、期待されるふるまい (expectation)

手順 (steps)

まず第一に開発者が必要とするのは、開発者自身のコンピュータ上で問題を再現する手順だ。これは、再現手順、もしくは単に手順と呼ばれる。scalaxb の実行方法を詳しく書いて、問題の発生に使われたスキーマや wsdl ドキュメントを全て提供する。もし生成されたコードを使用する際に問題が起こった場合は、サンプルコードも提供する。

再現ステップは、バグ報告で最も重要なものだ。 何らかの方法で、開発者が問題を再現することができなければ、不具合は修正することができない。エラーメッセージを教えるだけでは全く不十分だ。

問題 (problem)

次に、問題を詳しく書く。正確には、問題だと思われるものを詳しく書く。問題であることは「明らか」であるかもしれないが、後方互換性のための意図的な振る舞いであるかもしれない。コンパイルエラーの場合は、スタックトレースを含める。生の情報が多ければ多いほど助かる。

期待されるふるまい (expectation)

問題同様、期待されるふるまいだと思われるものを書く。

備考 (notes)

問題の解析ができているなら、追加で備考 (notes) セクションを作って書く。

サブジェクト

バグ報告のサブジェクトは、関係無い。より具体的なサブジェクトの方がいいが、正しいサブジェクトは問題の解析によるため、あまり気にする必要は無い。例えば、「生成されたコードがコンパイルできない」などで十分だ。

フォーマット

もし可能なら、github-flavored Markdown を使う。特に、以下のように ``` でコードやコンソールからの出力を囲う:

```scala
def core_getPluginByTextId(textId: String): Either[scalaxb.Fault[Any], SO_Plugin] = 
  soapClient.requestResponse(scala.xml.Elem(targetNamespace map {defaultScope.getPrefix(_)} getOrElse {""}, "core_getPluginByTextId", scala.xml.Null, defaultScope,
    scalaxb.toXML(textId, Some("http://www.sevone.com/"), "textId", defaultScope): _*), defaultScope, baseAddress, "POST", Some(new java.net.URI("urn:SevOneApi#SevOneApiServer#core_getPluginByTextId"))) match {
    case Left(x)  => Left(x)
    case Right(x) => Right(scalaxb.fromXML[SO_Plugin](x.head \ "return"))
  }
```

github では、上記は固定幅のフォントで Scala のシンタックスハイライトがかかって表示されるからだ。

コード

バグ報告の究極の方法は、github 上にその問題を例示したサンプルプロジェクトを公開することだ。開発者の同士場合は、Scala を使うのが最も効率的な形のコミュニケーションになることがある。自分で修正できる場合は、pull request を送る。

ケーススタディー

以下に、報告された問題に基づいて書かれた実際のバグレポートの例を見てみる。手順、問題、期待されるふるまい、サンプルコードの他に、XML Schema の仕様書から関係のある部分を抜粋してある:

xs:include without targetNamespace doesn't work

steps

  1. define schema B without targetNamesapce.
  2. define schema A that calls xs:include to include schema B.
  3. compile them.

problem

referenced complex type not found.

expectation

schema B is automatically interpreted to be in the same namespace as schema A.

note

see https://github.com/eed3si9n/scalaxb-sample/tree/ergogroup/detsentralefol...

also see XML Schema:

The XML Schema corresponding to <schema> contains not only the components corresponding to its definition and declaration [children], but also all the components of all the XML Schemas corresponding to any <include>d schema documents. Such included schema documents must either (a) have the same targetNamespace as the <include>ing schema document, or (b) no targetNamespace at all, in which case the <include>d schema document is converted to the <include>ing schema document's targetNamespace.