[prev in list] [next in list] [prev in thread] [next in thread] 

List:       xmlbeans-dev
Subject:    RE: Proposal for samples
From:       "David Remy" <dremy () bea ! com>
Date:       2004-06-30 19:16:11
Message-ID: 4B2B4C417991364996F035E1EE39E2E10190B545 () uskiex01 ! amer ! bea ! com
[Download RAW message or body]

Hey Steve,
Sorry it has taken a few days to get back to you.  This is great
work/thinking.  Samples are critical.

Some feedback inline.  

Overall +1.

> -----Original Message-----
> From: Steven Traut
> Sent: Friday, June 25, 2004 9:41 AM
> To: xmlbeans-dev@xml.apache.org
> Subject: Proposal for samples
> 
> 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.

i'll comment on this below, but i wonder if we should consider using
jira for submission of samples.  then the jira issue could be assigned
to a committer to get checked in.

> - 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.

I think this is an absolutely critical step that will probably have
implications on how we need the samples to be set up.  Running the
samples as a part of our checkin process (or at least regularly) will
keep them fresh and assure that they are still valid.  We will need some
sort of standard approach for designating the schemas that a sample is
dependent on so they can be built before actually executing the test.

I was talking to people about the samples at javaone and a couple asked
whether they would be junit.  At first I said no, that they were more
focused on the usage scenario, but after thinking more about it I think
we should consider the samples being junit.  That way the sample writer
could assure that the sample continues to have the expect output.  It
seems like you could still have all of the comments and user
friendliness of typical samples but run it in the form of a junit test
... 

> 
> 
> 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.

cool!  

> 
> 
> - 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?

it seems like this should be considered on a case by case basis.  which
does mean that samples are specific to a version so we will probably
need to root the samples are unique to a specific version.  i could
imagine, when we start work on a new version, that we would copy all of
the existing samples over to the new version and, as they start to
break, we would determine whether the usage scenario is still valid in
the new version and then either fix the sample or delete it.  similar to
tests.

> - Who reviews samples?

i think a committer should own getting a sample checked in.  

> - Should sample code package names be more strict or structured to
prevent
> conflicts? 

Yes, i think we will have to have a structure for packaging samples.
probably starting with xmlbeans.apache.org.samples plus the ones you
list below.  this is something the committer could help with but it
would be great for you to suggest gueslines.

Schemas will have the same issues.  We need to decide whether we want to
have a place for shared schemas and/or specific schemas for each sample.
in either case we will want to make sure we do not have target namespace
collisions.  it seems to me that it would be best if samples tended
towards using specific schemas in that sample (with a unique target
namespace) so that it would be easier for someone to download and run
the sample.   

> 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?

i wonder if we used jira whether that would be enough, the sample
submitter could just monitor the jira issue.

> - Do we want to include samples in the release download, or just make
them
> available from the web site?

from my perspective the website plus some sort of link in the readme
could be enough.  

One other thing I think we want to make sure that these samples are
internet searchable.  i think the xmlbeans public cvs directory can be
searchable as well as any wiki page we create so we are probably
covered.

> 
> 
> - 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.

consider using jira here?

> 
> - Make your subject line "Sample submission: <sample name>"

if we use jira we could create a category for samples.

> - 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

xmlbeans-dev will be copied on jira issue submission. 

> 
> 
> 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/


- ---------------------------------------------------------------------
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/


[prev in list] [next in list] [prev in thread] [next in thread]