For each sample project I think that it is a good idea to include an overview javadoc page that includes information about common setup etc. This would include essentually the same information that you outlined for the readme but provides a good means to link to external docs like specifications, traditional javadoc content such as APIs and can ( and should ) be placed on our website.
This is what I did for the SDO samples and I think that worked well. If people do not like it I can change it so that the it matches the desired readme format but I prefer the overview option so that it is consistent. Robbie On 9/6/06, Simon Laws <[EMAIL PROTECTED]> wrote:
On 9/5/06, Jean-Sebastien Delfino <[EMAIL PROTECTED]> wrote: > > Hi, > > I checked in a copy of Calculator under > > http://svn.apache.org/repos/asf/incubator/tuscany/cpp/sca/samples/Calculator-new/ > , > with a number of changes trying to simplify the sample and improve the > consistency of the names used in the sample: > - the subprojects follow the naming convention suggested in the SCA spec > and the various SCA white papers on osoa.org (sample.calculator, > sample.calculator.client etc.) helping create unique project names > - similar naming convention for the composite names > - changed Calculator subsystem to calculator solution > - the business interfaces are named Calculator and Divide instead of > CalculatorService, DivideService > - the components are named CalculatorComponent and DivideComponent > instead of CalculatorServiceComponent, DivideServiceComponent > - the services are named CalculatorService and DivideService > - and a few other minor cleanup changes, renamed readme.txt to README, > renamed the .cmd to .bat, changed the .bat to be consistent with the > .sh, and use the same executable name on Windows and Linux. > > If there's no objection, I plan to replace the existing Calculator > sample with this new form, and also check in an updated version of > Bigbank following the same pattern tomorrow. This will make our > implementation of the Bigbank sample much closer to what's described in > the OSOA Recursive Assembly white paper at > http://www.osoa.org/display/Main/Recursive+Assembly+Model. > > I'm not sure what we should put in the README for each sample. Right now > the contents of the README is Windows specific and probably obsolete, I > was thinking of maybe having another file besides the README called > HOWTO-DEPLOY describing how to deploy the sample to Axis2C... Comments > and thoughts welcome. > > -- > Jean-Sebastien > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > All sounds good to me. The README should have a description of what the sample does, what it is trying to demonstrate, and a summary of the various different configurations and platforms on which it will run. I.e. you might want to run the local or web services client on windows or *nix. So there will necessarily be quite a number of deployment and runtime instructions for what is actually a relatively simple demo. Your idea of having separate DEPLOY files for the different configurations sounds like the way to go. It might also be useful to include screen shots of the command line showing the run commands and the expected output. Also it would be good to have some discussion of how to turn debug on and what it shows you. This shouldn't be done on a sample by sample basis but I find it quite instructive. I have come across a set of typical configuration errors when using the samples, e.g. the one that always catches me is http://issues.apache.org/jira/browse/TUSCANY-499. We should create a samples FAQ I guess. There is quite a number of environement variables and paths that need to be set before it all works. We should review the run scripts to see if we can add more checking as they already check that appropriate environment variables are set. If you want some help with these things let me know. S
-- * * * Charlie * * * Check out some pics of little Charlie at http://www.flickr.com/photos/[EMAIL PROTECTED]/sets/ * * * Addresss * * * 1914 Overland Drive Chapel Hill NC 27517 * * * Number * * * 919-225-1553
