Author: husted Date: Tue Sep 6 13:00:15 2005 New Revision: 279082 URL: http://svn.apache.org/viewcvs?rev=279082&view=rev Log: Complete merger of Using and Helping.
Modified: struts/site/trunk/xdocs/acquiring.xml struts/site/trunk/xdocs/helping.xml Modified: struts/site/trunk/xdocs/acquiring.xml URL: http://svn.apache.org/viewcvs/struts/site/trunk/xdocs/acquiring.xml?rev=279082&r1=279081&r2=279082&view=diff ============================================================================== --- struts/site/trunk/xdocs/acquiring.xml (original) +++ struts/site/trunk/xdocs/acquiring.xml Tue Sep 6 13:00:15 2005 @@ -10,12 +10,12 @@ </properties> <body> - <section name="Acquiring Struts"> <a name="Acquiring"/> + <section name="Acquiring Apache Struts products"> <p> - Struts products are made available to the public at no charge in both - binary and source distributions under the + Apache Struts products are made available to the public at no charge + in both binary and source distributions under the <a href="http://apache.org/licenses/">Apache Software License</a>. Each subproject offers a production release, as well as a milestone releases and "nightly" development builds. @@ -23,13 +23,12 @@ <a href="http://maven.apache.org">Apache Maven</a> repositories, like <a href="http://ibiblio.org">ibiblio</a>. </p> -</section> -<section name="Releases and Milestone Builds"> +<subsection name="Releases and Milestone Builds"> <a name="ReleasesAndMilestones"/> <p> - Releases and milestone builds of Struts are available from the main - Struts distribution site, or from mirror sites. + Releases and milestone builds of Struts products are available from + the main Apache Struts distribution site, or from mirror sites. </p> <ul> <li> @@ -53,10 +52,10 @@ </ul> </li> </ul> -</section> +</subsection> -<section name="Development Builds"> <a name="DevelopmentBuilds"/> +<subsection name="Development Builds"> <p> The latest <em>development build</em> of Struts products are available @@ -68,7 +67,7 @@ <p> Development builds are being reviewed for quality - by the Struts community. + by the Apache Struts community. When a build is judged "ready for prime time", it is promoted to "General Availability" status and may be made the "Best Available" release. @@ -76,10 +75,10 @@ then it may be marked with "Beta" status. </p> -</section> +</subsection> -<section name="Nightly Builds"> <a name="NightlyBuilds"/> +<subsection name="Nightly Builds"> <p> For developers who are helping to create and maintain Struts products, @@ -109,10 +108,11 @@ so you have a better idea of what you are getting! </p> -</section> +</subsection> -<section name="Source Code"> <a name="SourceCode"/> +<subsection name="Source Code"> + <p> Access to the Apache Struts source repository is available through @@ -194,6 +194,7 @@ applications! </p> +</subsection> </section> Modified: struts/site/trunk/xdocs/helping.xml URL: http://svn.apache.org/viewcvs/struts/site/trunk/xdocs/helping.xml?rev=279082&r1=279081&r2=279082&view=diff ============================================================================== --- struts/site/trunk/xdocs/helping.xml (original) +++ struts/site/trunk/xdocs/helping.xml Tue Sep 6 13:00:15 2005 @@ -32,8 +32,11 @@ <li><a href="#corp"> What can my company do to help support Apache Struts? </a></li> + <li><a href="#patches"> + How can I create a patch? + </a></li> <li><a href="#bugs"> - How can I report bugs or make feature requests? + How can I report bugs or make feature suggestionss? </a></li> <li><a href="#contribute"> How can I contribute to the Apache Struts source code? @@ -146,66 +149,112 @@ <a name="corp"/> <subsection name="What can my company do to help support Apache Struts?"> -<p> -Apache Struts is an all volunteer product. -Our customers are the volunteers who donate their time and energy to -supporting the product. -If you want to support Struts, and become one of our customers, -then you need to get involved and become a volunteer. -</p> - -<p> -Our challenge to any team using an Apache Struts product is to donate the time of one team member -one afternoon a week (or more if you can spare the resources). -Have your team member browse -<a href="#bugs">Bugzilla</a> for any issues -without a patch or unit test, -and <a href="#contribute">add the patch or test</a>. -Please note that we do not use @author tags in our JavaDocs and documentation. -If your patch includes an @author tag, we would have to ask that it be removed. -</p> - -<p> - If an Apache Struts product doesn't do what <em>you</em> want, - it's up to <strong>you</strong> to step up and propose the patch. - If an Apache Struts product doesn't ship as often as you would like, - it's up to you to step up with the tests and fixes that get a release out - the door. - (<a href="http://jakarta.apache.org/site/contributing.html">Like Craig - McClanahan did for Tomcat.</a>) -</p> - -<p> -If Struts does do what you want, help others become involved by turning your -war stories into FAQs and how-tos that we can make part of the -<a href="#documentation">documentation</a>. -The mailing list is very active and trundling through the archives is no -picnic. -We can always use volunteers who can reduce the best threads to coherent articles -to share with others. -</p> - -<p> -Some Apache products like you to submit your patch to the mailing list. -We would prefer that you create a -<a href="http://issues.apache.org/bugzilla">Bugzilla</a> -Bugzilla report and then attach the patch to the report. -To do this, you must first create the report, -and then modify the report to add your patch. -We realize this is a bit clumsy, but it keeps us from losing things, -and helps to ensure that your patch will be attended. -</p> - -<p> -We don't sell Struts for money, but anyone who wants to be our customer -can pay us back by donating the time and energy that money represents. -</p> + <p> + Apache Struts is an all volunteer product. + Our customers are the volunteers who donate their time and energy to + supporting the product. + If you want to support Struts, and become one of our customers, + then you need to get involved and become a volunteer. + </p> + + <p> + Our challenge to any team using an Apache Struts product + is to donate the time of one team member + one afternoon a week (or more if you can spare the resources). + Have your team member browse + <a href="#bugs">Bugzilla</a> for any issues + without a <a href="#patches">patch</a> or unit test, + and <a href="#contribute">add the patch or test</a>. + Please note that we do not use @author tags in our JavaDocs and + documentation. + If your patch includes an @author tag, we would have to ask that it be removed. + </p> + + <p> + If an Apache Struts product doesn't do what <em>you</em> want, + it's up to <strong>you</strong> to step up and propose the patch. + If an Apache Struts product doesn't ship as often as you would like, + it's up to you to step up with the tests and fixes that get a release out + the door. + (<a href="http://jakarta.apache.org/site/contributing.html">Like Craig + McClanahan did for Tomcat.</a>) + </p> + + <p> + If Struts does do what you want, help others become involved by turning your + war stories into FAQs and how-tos that we can make part of the + <a href="#documentation">documentation</a>. + The mailing list is very active and + trundling through the archives is no picnic. + We can always use volunteers who can reduce the best threads + to coherent articles we can share with others. + </p> + + <p> + We don't sell Struts for money, but anyone who wants to be our customer + can pay us back by donating the time and energy that money represents. + </p> + +</subsection> + +<a name="patches"/> +<subsection name="How do I create a patch?"> + <p> + A patch is a machine-readable script that can automatically + recreate a change to a text file, including source code and + documentation. + The patch format is also human-readable. + Developers often pass patches around to discuss a change before + applying it to the main repository. + </p> + + <p> + The best way to affect a change to the source code or documentation + is to provide a patch. + Apache Struts committers can then review your patch and decide + whether to apply it to the main repository. + </p> + + <p> + To create a patch, you first have to + <a href="file:///e:/projects/Apache/struts/site/target/docs/acquiring.html#Source_Code"> + checkout</a> a copy of the sourcecode or documentation from the main + repository. + You can then change your copy, and create the patch using + a simple <a href="http://subversion.org/">Subversion</a> + command, like this: + </p> + + <p> + svn diff Main.java >> patchfile.txt + </p> + + <p> + Then, create a <a href="http://issues.apache.org/bugzilla">Bugzilla + report</a> about the change, and attach the patch file. + </p> + + <p> + Some Apache products like you to submit your patch to the mailing list. + We would prefer that you create a + <a href="http://issues.apache.org/bugzilla">Bugzilla</a> + report and then attach the patch to the report. + To do this, you must first create the report, + and then modify the report to add your patch. + We realize this is a bit clumsy, but it keeps us from losing things, + and helps to ensure that your patch will be attended. + </p> + + <p> + The <a href="http://www.netbeans.org/community/contribute/patches.html"> + NetBeans community</a> also has a helpful section on the + subject of creating patches. + </p> </subsection> <a name="bugs"/> <subsection name="How can I report bugs or suggest features?"> - <p> Tracking of bug reports and enhancement suggestions for Apache Struts subprojects is handled @@ -222,104 +271,92 @@ </p> <p> -You can research and report outstanding fixes and feature requests using -<a href="http://issues.apache.org/bugzilla">Bugzilla</a>. -If you are unsure if this is an actual problem, feel free to bring it up the -list first. -But to be sure that an issue is resolved, read -<a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"> -How to Report Bugs Effectively</a> and report it to -<a href="http://issues.apache.org/bugzilla"><strong>Bugzilla</strong></a>. -</p> - -<p> -Feature suggestions are also maintained in the Bugzilla database. -</p> - -<p> -<a href="http://jakarta.apache.org/site/source.html">Patches</a> are always -welcome. -If you can't write a patch to fix your bug, a -<a href="kickstart.html#tests">unit test</a> -that demonstrates the problem is also welcome. -(And, of course, unit tests that prove your patch works are equally welcome.) -</p> - -<p> -If your bug or feature is already in Bugzilla, <strong>you can vote</strong> -for the issue and call more attention to it. -Each user can cast up to six votes at a time. -</p> - -<p> -If there is a patch attached to the issue, you can also try applying -to your local copy of Struts, and report whether it worked for you. -Feedback from developers regarding a proposed patch is really quite -helpful. -Don't hesitate to add a "works for me" note to a ticket if you've tried the -patch yourself and found it useful. -</p> + You can research and report outstanding fixes and feature suggestions + using <a href="http://issues.apache.org/bugzilla">Bugzilla</a>. + If you are unsure if this is an actual problem, + feel free to bring it up on the list first. + But to be sure that an issue is resolved, read + <a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"> + How to Report Bugs Effectively</a> and report it to + <a href="http://issues.apache.org/bugzilla"><strong>Bugzilla</strong></a>. + </p> + + <p> + If you can't write a <a href="#patches">patch</a> to fix your bug, + a unit test that demonstrates the problem is also welcome. + (And, of course, unit tests that prove your patch works + are equally welcome.) + </p> + + <p> + If your bug or feature is already in Bugzilla, + you can vote for the issue and call more attention to it. + Each user can cast up to six votes at a time. + </p> + <p> + If there is a patch attached to the issue, you can also try applying + to your local copy of Struts, and report whether it worked for you. + Feedback from developers regarding a proposed patch is really quite + helpful. + Don't hesitate to add a "works for me" note to a ticket + if you've tried the patch yourself and found it useful. + </p> + + <p> + Feature suggestions are also maintained in the Bugzilla database. + </p> </subsection> <a name="contribute"/> <subsection name="How can I contribute to the Struts source code?"> <p> - A very good place to start is by <strong>reviewing the list of open issues</strong> - and pending feature requests (<a href="#bugs">Bugzilla</a>). - If you see an issue that needs a patch you can write, - feel free to annex your patch. - If you seen an issue that needs a unit test to prove its fixed, - feel free to annex your test case. - If someone has posted a patch to an issue you'd like to see resolved, - apply the patch to your local development copy of Struts. - Then let us know if it works for you, and if it does, - cast your vote for the issue and its patch. + A very good place to start is by <strong>reviewing the list of open issues</strong> + and pending feature suggestions (<a href="#bugs">Bugzilla</a>). + If you see an issue that needs a patch you can write, + feel free to annex your patch. + If you seen an issue that needs a unit test to prove its fixed, + feel free to annex your test case. + If someone has posted a patch to an issue you'd like to see resolved, + apply the patch to your local development copy of Struts. + Then let us know if it works for you, and if it does, + cast your vote for the issue and its patch. </p> <p> - If none of the pending issues scratch your itch, - another good place to start is by <strong>contributing unit tests</strong> - for existing features (even those that still work). + If none of the pending issues scratch your itch, + another good place to start is by <strong>contributing unit tests</strong> + for existing features (even those that still work). </p> <p> You can upload a proposed - <a href="http://jakarta.apache.org/site/source.html#Patches">patch</a> - to either the code or documentation by creating a feature request in - <a href="#Bugs">Bugzilla</a>. + <a href="#patches">patch</a> + to either the code or documentation by creating a feature suggestion + in <a href="#Bugs">Bugzilla</a>. <strong>After creating the ticket</strong>, you can go back and upload a file containing your patch. </p> <p> - (For more about creating patches, see the - <a href="http://jakarta.apache.org/site/source.html">Jakarta Project - Guidelines</a>. - The <a href="http://www.netbeans.org/community/contribute/patches.html"> - NetBeans community section</a> also has a helpful section on the same - subject. + Our current approach to <a href="kickstart.html#tests">unit testing</a> + works fairly well for exercising most method-level stuff, but does + not really address situations of dynamic behavior -- most particularly the + execution of custom tags for Struts. + You can try to fake what a JSP container does, but a much more reliable + testing regime would actually execute the tag in a real container. + For that purpose, we use the + <a href="http://jakarta.apache.org/cactus">Cactus</a> testing framework, + which re-executes the JUnit-based tests as well to make sure that nothing + bad happens when you switch environments. + Right now, there are very few dynamic tests; ideally, we will have tests + for every tag, that cover every reasonable combination of tag attribute + values (yes, that's a tall order -- the totally lines of test source code + will undoubtedly exceed the totally lines of code in the framework itself + if we achieve this). </p> -<p> -Our current approach to <a href="kickstart.html#tests">unit testing</a> -works fairly well for exercising most method-level stuff, but does -not really address situations of dynamic behavior -- most particularly the -execution of custom tags for Struts. -You can try to fake what a JSP container does, but a much more reliable -testing regime would actually execute the tag in a real container. -For that purpose, we use the -<a href="http://jakarta.apache.org/cactus">Cactus</a> testing framework, -which re-executes the JUnit-based tests as well to make sure that nothing -bad happens when you switch environments. -Right now, there are very few dynamic tests; ideally, we will have tests -for every tag, that cover every reasonable combination of tag attribute -values (yes, that's a tall order -- the totally lines of test source code -will undoubtedly exceed the totally lines of code in the framework itself -if we achieve this). -</p> - </subsection> <a name="documentation"/> @@ -332,11 +369,11 @@ change to the subprojects trunk directory and run 'maven site'. </p> -<p> -The only difference is that the documentation is kept in XML rather than Java -source code. -Otherwise, all the same precepts and procedures pertain. -</p> + <p> + The only difference is that the documentation is kept in XML rather + than Java source code. + Otherwise, all the same precepts and procedures pertain. + </p> <p> If you would like to help with the documentation, it is important to @@ -360,170 +397,160 @@ documentation so that it becomes part of a Struts distribution. </p> -<p> -The trick to getting started is to download the nightly build and try building -the subproject's site. -Then try adding your own XML page under xdocs/ to see if the build succeeds. -If it doesn't, it will report where the bad element is, much like it reports -where a bad programming expression is. -If it does, then your page should be available under target/documentation/. -</p> - -<p> -To display markup, substitute &lt; for <. -The unmatched trailing > will be ignored. -Since it is XML, all elements also need to closed. -So elements like <br> and <hr> need to set out as <br/> and <hr/>. -</p> - -<p> -Also watch for the length of code samples - -these do not wrap. -If a line is too long, it will force the right margin out past the edge of the -screen or printed page. -</p> - -<p> -The stylesheets we use are adequate, but could certainly be improved by an XML -guru, if you happen to one of those. -</p> + <p> + The trick to getting started is to download the nightly build and try + building the subproject's site. + Then try adding your own XML page under xdocs/ to see if the build succeeds. + If it doesn't, it will report where the bad element is, much like it reports + where a bad programming expression is. + If it does, then your page should be available under target/documentation/. + </p> + <p> + To display markup, substitute &lt; for <. + The unmatched trailing > will be ignored. + Since it is XML, all elements also need to closed. + So elements like <br> and <hr> need to set out as <br/> and <hr/>. + </p> <p> - You can also post documentation to the - <a href="wiki.apache.org/struts/">Struts Wiki</a>. + Also watch for the length of code samples - these do not wrap. + If a line is too long, + it will force the right margin out past the edge of the screen or + printed page. </p> + <p> + You can also post documentation to the + <a href="wiki.apache.org/struts/">Struts Wiki</a>. + </p> </subsection> <a name="release"/> <subsection name="So when is the next release coming out?"> -<p> -Here is the truth regarding releases: -</p> - -<p> - -Apache products are released on the basis of merit, and ~not~ according -to a strict timetable. -The volunteers devote whatever time they can to work on the product. -But all volunteers have real jobs and real lives, that do take precedence. -Since Struts does not have paid personnel working on the project, -we simply cannot make date-oriented commitments. -</p> - -<p> -The bottom line is that Apache takes releases very seriously. -We do not compromise the quality of our software by watching the calendar -(and then ship something ready or not). -A release is ready when it is ready. -</p> - -<p> -That may sound flip, but it ~is~ the truth. -The delivery of production-quality, leading-edge software is not something -anyone can prognosticate. -If anyone tries, they are lying to you. -That, we won't do ;-) -</p> - -<p> -What we ~will~ do is release all of our development software as soon as it is -developed. -This way you can judge for yourself how quickly the development is proceeding, -and whether what is being developed will meet your needs. -If you need a feature right now, you can use the nightly build, or roll your -own patch. -There are no internal code repositories, private development lists, -secret chat rooms, or conference calls. -What you see is what we got. -If you are following the DEV list, then you know everything the developers -know. -Really, you do. -</p> - -<p> -<em>So, what do you tell your team?</em> -If you can ship your application based on the nightly build of your choice, -then consider that an option. -You can still ship yours, even if we don't ship ours, -and you will have access to all the latest patches or enhancements. -(Just like we were working down the hall.) -If you can only ship your application based on a release build of Struts, -then you should base your development on the release build of Struts, -and keep an eye on what is coming down the pipeline. -This way you are at least forewarned and forearmed. -</p> + <p> + Here is the truth regarding releases: + </p> + + <p> + Apache products are released on the basis of merit, + and ~not~ according to a strict timetable. + The volunteers devote whatever time they can to work on the product. + But all volunteers have real jobs and real lives, that do take precedence. + Since Struts does not have paid personnel working on the project, + we simply cannot make date-oriented commitments. + </p> + + <p> + The bottom line is that Apache takes releases very seriously. + We do not compromise the quality of our software by watching the calendar + (and then ship something ready or not). + A release is ready when it is ready. + </p> + + <p> + That may sound flip, but it ~is~ the truth. + The delivery of production-quality, leading-edge software is + not something anyone can prognosticate. + If anyone tries, they are lying to you. + That, we won't do ;-) + </p> + + <p> + What we ~will~ do is release all of our development software as soon as + it is developed. + This way you can judge for yourself how quickly the development is + proceeding, and whether what is being developed will meet your needs. + If you need a feature right now, you can use the nightly build, or roll + your own patch. + There are no internal code repositories, private development lists, + secret chat rooms, or conference calls. + What you see is what we got. + If you are following the DEV list, then you know everything the + developers know. + Really, you do. + </p> + + <p> + <em>So, what do you tell your team?</em> + If you can ship your application based on the nightly build of your choice, + then consider that an option. + You can still ship yours, even if we don't ship ours, + and you will have access to all the latest patches or enhancements. + (Just like we were working down the hall.) + If you can only ship your application based on a release build of Struts, + then you should base your development on the release build of Struts, + and keep an eye on what is coming down the pipeline. + This way you are at least forewarned and forearmed. + </p> </subsection> <a name="release_help"/> <subsection name="What can I do to help the next release along?"> -<ul> - -<li> - Most importantly, download the latest nightly build or development release - and test it against your own applications. - Report any and all issues or suspected issues to - <a href="http://issues.apache.org/bugzilla">Bugzilla</a>. - The sooner we resolve any problems, the fewer betas or release candidates - we will have to distribute before we are done. - (How do we know when we're done? -- When we run out of issues =:o) - The sooner we find them, the sooner we are done.) -</li> - -<li> - <strong>Contribute <a href="kickstart.html#tests">unit tests</a></strong>. - The closer we get to a release, the more we worry about breaking something. - The more tests we have, the more confident we can be when applying patches. - Tests that prove that a pending issue is actually a bug are the most - welcome ones. - But we are eager for any and all tests for any and all features, - even those that still work =:0). -</li> - -<li> - <strong>Review the list of issues</strong> at <a href="#bugs">Bugzilla</a>. - If there are any to which you can respond, please do. - If there any patches posted, feel free to test them your system, - report the results, and cast your vote if they work. -</li> - -<li> - <strong>Confirm an issue's category and status</strong>. - Newbies often post feature requests or help-desk questions as "bugs". - This bloats the list of fixes we (apparently) need to apply before the next - beta, making it hard to see the forest for the trees. - If an issue doesn't seem to be categorized correctly, exercise your best - judgment and change it. - If one ticket seems like a duplicate of another, go ahead and enter the - change. - Every modification to the ticket is echoed to the DEV list and - automatically subjected to peer review. - Err on the side of doing. -</li> - -<li> - Use Bugzilla to <strong>vote for issues</strong> you feel should be handled - first. - If an issue on your ballot doesn't include a patch, feel free to try coding - one yourself. - (In a meritocracy, patches are the only votes that matter.) - Dozens of developers have contributed code or documentation to Struts. - You can too =:0) -</li> - -<li> - <strong>Answer questions on the user list.</strong> - The Committers only have a limited amount of time to volunteer. - If Developers are supporting each other on the lists, - the Committers have more time to spend on the next release. -</li> - -</ul> + <ul> + <li> + Most importantly, download the latest nightly build or development release + and test it against your own applications. + Report any and all issues or suspected issues to + <a href="http://issues.apache.org/bugzilla">Bugzilla</a>. + The sooner we resolve any problems, the fewer betas or release candidates + we will have to distribute before we are done. + (How do we know when we're done? -- When we run out of issues =:o) + The sooner we find them, the sooner we are done.) + </li> + + <li> + <strong>Contribute <a href="kickstart.html#tests">unit tests</a></strong>. + The closer we get to a release, the more we worry about breaking something. + The more tests we have, the more confident we can be when applying patches. + Tests that prove that a pending issue is actually a bug are the most + welcome ones. + But we are eager for any and all tests for any and all features, + even those that still work =:0). + </li> + + <li> + <strong>Review the list of issues</strong> at <a href="#bugs">Bugzilla</a>. + If there are any to which you can respond, please do. + If there any patches posted, feel free to test them your system, + report the results, and cast your vote if they work. + </li> + + <li> + <strong>Confirm an issue's category and status</strong>. + Newbies often post feature suggestions or help-desk questions as "bugs". + This bloats the list of fixes we (apparently) need to apply before the next + beta, making it hard to see the forest for the trees. + If an issue doesn't seem to be categorized correctly, + exercise your best judgment and change it. + If one ticket seems like a duplicate of another, + go ahead and enter the change. + Every modification to the ticket is echoed to the DEV list and + automatically subjected to peer review. + Err on the side of doing. + </li> + + <li> + Use Bugzilla to <strong>vote for issues</strong> + you feel should be handle first. + If an issue on your ballot doesn't include a patch, + feel free to try coding one yourself. + (In a meritocracy, patches are the only votes that matter.) + Dozens of developers have contributed code or documentation to Struts. + You can too =:0) + </li> + + <li> + <strong>Answer questions on the user list.</strong> + The Committers only have a limited amount of time to volunteer. + If Developers are supporting each other on the lists, + the Committers have more time to spend on the next release. + </li> + </ul> </subsection> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]