issue reporting guideline

Effective bug reports are more likely to be fixed. These guidelines explain how to write such reports.

preliminaries

• Make sure your software is up to date.
• Search github issues to see whether your bug has already been reported.
• Open one case for each problem.
• Proceed to the next steps for details.

where to file a bug report

• For most of the issues you encounter using scalaxb, use GitHub issues to report bugs.
• If it's more of an open question, enhancement idea, or an interesting issue, bring it up to GitHub Discussions or Google Group.
• If it's sensitive material, send me a email (eed3si9n at gmail) clearly stating that it's a sensitive material.

Google Group is for general discussions and announcements concerning scalaxb.

You may think it's better to phrase a bug report as a general "question" in case it's not program's bug. Don't worry about it. The developers don't get offended by invalid bug reports.

how to file a bug report

The developers need three things from you: steps, problem, and expectation.

steps

First and foremost, the developers need exact steps to reproduce your problems on his/her computer. This is called reproduction steps, which is often shortened to "repro steps" or "steps." Describe your method of running scalaxb. Provide the schema or wsdl document that was used that caused the problem. Provide sample Scala code if it's to do with usage of the generated code.

Repro steps are the most important part of a bug report. If the developers cannot reproduce the problem in one way or the other, the problem can't be fixed. Telling them the error messages is not enough.

problem

Next, describe the problem, or what you think is the problem. It might be "obvious" to you that it's a problem, but it could actually be an intentional behavior for some backward compatibility etc. For complication errors, include stack trace. More raw info the better.

expectation

Same as the problem. Describe what you think should've happened.

notes

Add an optional notes section to describe your analysis.

subject

The subject of the bug report doesn't matter. A more descriptive subject is certainly better, but a good subject really depends on the analysis of the problem, so don't worry too much about it. "Generated code doesn't compile" is good enough.

formatting

If possible, use github-flavored Markdown. In particular, use ``` to quote code or console outputs as follows:

```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"))
  }
```

On github, the above will be displayed nicely in fixed width font with Scala syntax highlights.

code

The ultimate way of reporting a bug, is having a sample project up on github presenting the issue. After all, we are talking about developers. Using Scala sometimes is the most effective form of communication. Send pull requests, if you can fix it yourself.

case study

Here's an actual bug report based on a reported issue. There are steps, problem, expectation, sample code, and the relevant section from XML Schema spec.

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.