Proposal for samples

[Steven Traut <st...@bea.com>]

Hello all -- Here's a suggested approach for accepting and handling XMLBeans samples. Feedback is most welcome. (I should note that I tried sending this mail with a sample ZIP attached, but it bounced -- the list appears not to accept ZIP attachments. Would some other format work?)

Apologies in advance for the length of this email. Basically it breaks down into these parts:

Suggestion overview
Questions
Guidelines for sample authors

- Overview -

In the near term I think we can do the following:

- Provide a page on the wiki to list sample ideas, and to let users submit new ones to the list. (I can make this page). Link to this from the Documentation and (new) Samples page.
- Provide a place in CVS for storing samples. Wherever this is, I suggest its subdirectories be the names of the samples accepted. For example, this might result in <root>/samples/MixedContent or <root>/samples/ValidationErrorReporter, with respective zips and source contained in each. This gives us a way to store both the downloadable ZIPs and the exploded source for use in tests (and, potentially, to search in and display in pages on the site).
- Receive sample submissions via xmlbeans-dev@xml.apache.org, as described in the guidelines below.
- Review submissions (as described below) and make them available for download if approved.
- Provide a page at the XMLBeans web site that lists available samples, along with brief descriptions and a download link. (I can do this once we have downloadable samples).
- Incorporate samples into test suites and XMLBeans build process.


Longer term, I think we can do a lot to improve the process, particularly to make uploading and finding samples easier. Here are a few ideas:

- Provide a page at the XMLBeans web site that includes a form for uploading samples. The form would include fields for sample name, a brief description, XMLBeans version, and contact email. It could also include check boxes for predefined sample categories, as described below.
- Define keywords for sample categories. Imagine having a page that lists samples in a table with three columns -- the sample name, a brief description, and a comma-separated list of categories such as "Cursor: XQuery," "Schema: Enums," "Schema: Dynamic Compilation," or "Type System".
- Provide the ability for the user to search or filter samples in the list based on category.
- Store sample information, including keywords, in an XML file that's used to populate the HTML table and potentially for searching and sorting.


- Questions -

- As XMLBeans evolves, should there be a process for verifying samples against new versions, and for updating them if needed? Or should broken samples be left behind?
- Who reviews samples?
- Should sample code package names be more strict or structured to prevent conflicts? Will they be compiled together? For example, we might ask that package names start with the XMLBeans technology area the sample focuses on, like schema.anytype.* or cursor.pushpop.* or xquery.flwr.*
- Do we really want to contact submitters after reviewing their sample -- or at all?
- Do we want to include samples in the release download, or just make them available from the web site?


- Guidelines -

I've suggested sample authoring guidelines below. Because I think the message to potential authors is important (and to save time down the road), I've written this as if it were a page on the web site, rather than abstracted guidelines. I think these should also be downloadable as a text file.


Guidelines for Sample Authors

Thanks for considering becoming an XMLBeans sample author! Because we want all of the samples available from this site to be useful (and you probably do, too), we'd like you to follow the guidelines on this page when writing an XMLBeans sample.

Note: All sample code accepted for use on the XMLBeans web site becomes the property of the Apache Software Foundation. In other words, thanks for donating a sample!


Sample scope

- Try to keep your sample reasonably small and well-defined. It's going to be more useful, and more easily found, if it's about something specific -- handling schema enums (or some other particular aspect of schema), handling validation errors, constructing mixed content with a cursor, and so on. Large samples that do lots of things are often hard to get to know and learn something useful from. For suggestions, see "Ideas for XMLBeans Samples."
- Your code will be most useful if it can be copied and pasted into someone else's app. However, schema dependencies will differ greatly from user to user, so samples that use generated types will tend to be fairly specific. Moreover, code that effectively demonstrates how a particular aspect of XMLBeans works is a good teacher, even if would take quite a bit of massaging to coerce it to another application.


Code comments

Obviously, comments are an essential part of making a sample useful. In general, the more comments your code has, the better. But here are a few guidelines that we ask you to keep in mind.

- Each sample file (including non-Java files) must include the Apache copyright notice. If it's not there when it's accepted, we'll add it.
- Each class and method should include a comment in the Javadoc style. It's not necessary to include specific Javadoc annotations (@param, @return, and so on), but your sample isn't as useful to others unless it's commented well.
- Class-level comments should describe what the class demonstrates. In particular, the comments should be sure to describe the XMLBeans technologies that the class includes. Other description text should describe what the sample's user should expect to see when they run the sample.
- Method-level comments should describe what the method does. Comments should focus on the role of XMLBeans technologies.
- Where useful, add more comments!


Code conventions

To help make XMLBeans samples as a set easier for others to use, we encourage you to follow a few simple code conventions. In this way, users can spend less time deciphering code and more time getting the things it demonstrates. Most of these are common practice anyway.

- Package name words should be all lower-case.
- Package names should begin with the sample's name, and should indicate what the sample illustrates. Examples are anytype.*, dynamiccompilation.*, or elementsequence.*
- Class names should be initial-capped and camel-cased. Names should say something about what the sample illustrates or what it does. Examples are ValidationErrorReporter and SequenceWalker.
- It's a good idea to keep variable declarations and assignments separate from the variable's use. This makes the code easier to read, and makes it a little easier for IDE users to explore your code with breakpoints.


Packaging your sample

To help keep the user's experience consistent among samples, please use the following guidelines for putting your sample together in the package you send to us.

- Package your sample files into a ZIP file whose name is the sample's name, such as MixedContent.zip.
- Include a readme.txt file. The readme should include:
   - A brief description of what the sample illustrates and does.
   - Notes about any dependencies the user should be aware of.
   - Instructions the user might need to use the sample.
- Your ZIP file should use the following directory hierarchy (of course, there may be cases where your sample's particular needs require a variation on this structure):
     <root>
         readme.txt
         bin
             [scripts or executables]
         lib [required re-distributable libraries]
             *.jar
         schemas
             *.xsd
             *.xsdconfig
         src
             *.java
         xmlinstances
             *.xml


Submitting your sample

With your sample ZIP in hand, compose an email to submit your sample. Unless you note otherwise, your return email address is the one we'll use to contact you.

- Make your subject line "Sample submission: <sample name>"
- In the body of the email, include a brief description of the sample, maybe based on the one in your readme. This should be no more than a sentence or two.
- Attach your ZIP file.
- Send the email to xmlbeans-dev@xml.apache.org


Code review

After being received by the XMLBeans team, your sample code will be reviewed before it's included on the web site for download. If your sample is accepted, we'll let you know using your return email address. If for some reason we can't accept it, we'll let you know with suggestions for resubmitting it. 

The code review will include:

- Ensuring that the sample builds and runs as described.
- Checking that comments are reasonably complete.
- Ensuring that the sample code includes the copyright notice.


Thanks for submitting!



- ---------------------------------------------------------------------
To unsubscribe, e-mail:   xmlbeans-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xmlbeans-dev-help@xml.apache.org
Apache XMLBeans Project -- URL: http://xml.apache.org/xmlbeans/

Re: Proposal for samples

[David Waite <ma...@akuma.org>]

I wonder if it would also be nice to have a self-service wiki page for 
projects using xmlbeans.

-David Waite

On Jun 25, 2004, at 10:41 AM, Steven Traut wrote:

> Hello all -- Here's a suggested approach for accepting and handling 
> XMLBeans samples. Feedback is most welcome. (I should note that I 
> tried sending this mail with a sample ZIP attached, but it bounced -- 
> the list appears not to accept ZIP attachments. Would some other 
> format work?)
>
> Apologies in advance for the length of this email. Basically it breaks 
> down into these parts:


- ---------------------------------------------------------------------
To unsubscribe, e-mail:   xmlbeans-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xmlbeans-dev-help@xml.apache.org
Apache XMLBeans Project -- URL: http://xml.apache.org/xmlbeans/

Re: Proposal for samples

[David Waite <ma...@akuma.org>]

I wonder if it would also be nice to have a self-service wiki page for 
projects using xmlbeans.

-David Waite

On Jun 25, 2004, at 10:41 AM, Steven Traut wrote:

> Hello all -- Here's a suggested approach for accepting and handling 
> XMLBeans samples. Feedback is most welcome. (I should note that I 
> tried sending this mail with a sample ZIP attached, but it bounced -- 
> the list appears not to accept ZIP attachments. Would some other 
> format work?)
>
> Apologies in advance for the length of this email. Basically it breaks 
> down into these parts:


- ---------------------------------------------------------------------
To unsubscribe, e-mail:   xmlbeans-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xmlbeans-dev-help@xml.apache.org
Apache XMLBeans Project -- URL: http://xml.apache.org/xmlbeans/