husted 2002/12/22 09:09:01 Modified: doc/faqs helping.xml Log: Conform line lengths - no content changes. Revision Changes Path 1.4 +228 -157 jakarta-struts/doc/faqs/helping.xml Index: helping.xml =================================================================== RCS file: /home/cvs/jakarta-struts/doc/faqs/helping.xml,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- helping.xml 22 Dec 2002 16:56:00 -0000 1.3 +++ helping.xml 22 Dec 2002 17:09:01 -0000 1.4 @@ -13,18 +13,34 @@ <section href="contents" name="Index"> <p> -<font face="Arial, Helvetica, sans serif">"You can't always get what you want / but if you try real hard / you might just find / -that you get what you need". </font><br/> +<font face="Arial, Helvetica, sans serif"> +"You can't always get what you want / +but if you try real hard / +you might just find / +that you get what you need". +</font><br/> [Rolling Stones] </p> <ul> - <li><a href="#corp">What can my company do to help support Struts?</a></li> - <li><a href="#bugs">How can I report bugs or make feature requests?</a></li> - <li><a href="#contribute">How can I contribute to Struts source code?</a></li> - <li><a href="#documentation">How can I contribute to the documentation?</a></li> - <li><a href="#release">So when is the next release coming out?</a></li> - <li><a href="#release_help">How can I help the next release along?</a></li> + <li><a href="#corp"> + What can my company do to help support Struts? + </a></li> + <li><a href="#bugs"> + How can I report bugs or make feature requests? + </a></li> + <li><a href="#contribute"> + How can I contribute to Struts source code? + </a></li> + <li><a href="#documentation"> + How can I contribute to the documentation? + </a></li> + <li><a href="#release"> + So when is the next release coming out? + </a></li> + <li><a href="#release_help"> + How can I help the next release along? + </a></li> </ul> </section> @@ -32,10 +48,13 @@ <section href="corp" name="What can my company do to help support Struts?"> <p> -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 -<a href="http://jakarta.apache.org/site/getinvolved.html";>get involved</a> and become a volunteer. +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 +<a href="http://jakarta.apache.org/site/getinvolved.html";>get involved</a> +and become a volunteer. </p> <p> @@ -50,16 +69,20 @@ </p> <p> -If Struts doesn't do what <i>you</i> want, it's up to <b>you</b> to step up and propose the patch. -If Struts 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. +If Struts doesn't do what <i>you</i> want, it's up to <b>you</b> to step up +and propose the patch. +If Struts 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. </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 people who can reduce the best -threads to coherent articles that we can put in the User Guide. +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 people who can reduce the best threads to coherent articles +that we can put in the User Guide. </p> <p> @@ -74,8 +97,8 @@ </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. +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> </section> @@ -84,128 +107,148 @@ <p> You can research and report outstanding fixes and feature requests using -<a href="http://jakarta.apache.org/site/bugs.html";>Jakarta Bugzilla</a>. If you -are unsure if this is an actual problem, feel free to bring it up the list -first. But to 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://jakarta.apache.org/site/bugs.html";>Jakarta Bugzilla</a>. +If you are unsure if this is an actual problem, feel free to bring it up the +list first. +But to 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://jakarta.apache.org/site/bugs.html";><b>Bugzilla</b></a>. </p> <p> -Feature requests are also maintained in the Bugzilla database. Some older -requests are still listed the <a href="../todo-1.1.html">wish list</a> -page. +Feature requests are also maintained in the Bugzilla database. +Some older requests are still listed the +<a href="../todo-1.1.html">wish list</a> page. </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="#tests">unit test</a> +welcome. +If you can't write a patch to fix your bug, a <a href="#tests">unit test</a> that demonstrates the problem is also welcome. -(And, of course, unit tests that prove your patch work are equally -welcome.) +(And, of course, unit tests that prove your patch work 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. +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 "me too" if you've tried the patch yourself. +helpful. +Don't hesitate to "me too" if you've tried the patch yourself. </p> </section> -<section href="contribute" name="How can I contribute to the Struts source code?"> +<section href="contribute" + name="How can I contribute to the Struts source code?"> <p> -Struts is distributed by the <a href="http://apache.org/";>Apache Software Foundation</a>. -These are the same people who distribute the Apache Web server. Like all ASF projects, Struts -is managed as a "meritocracy", where everyone's contribution is welcome. Users can -help other users the <a href="http://jakarta.apache.org/site/mail.html";>mailing lists</a>, +Struts is distributed by the <a href="http://apache.org/";> +Apache Software Foundation</a>. +These are the same people who distribute the Apache Web server. +Like all ASF projects, Struts is managed as a "meritocracy", +where everyone's contribution is welcome. +Users can help other users the +<a href="http://jakarta.apache.org/site/mail.html";>mailing lists</a>, <a href="http://jakarta.apache.org/site/bugs.html";>report bugs</a>, and -<a href="http://jakarta.apache.org/site/bugs.html";>request new features</a>. Developers can -contribute patches, new code, and documentation. The most active Developers may become -<a href="http://jakarta.apache.org/site/roles.html";>Committers</a>, who make the actual -decisions about Strut's codebase. +<a href="http://jakarta.apache.org/site/bugs.html";>request new features</a>. +Developers can +contribute patches, new code, and documentation. +The most active Developers may become +<a href="http://jakarta.apache.org/site/roles.html";>Committers</a>, +who make the actual decisions about Strut's codebase. </p> <p> If you are new to open source development, see the -"<a href="http://jakarta.apache.org/site/getinvolved.html";>How to get involved</a>" -page the main Jakarta site. +"<a href="http://jakarta.apache.org/site/getinvolved.html";> +How to get involved</a>" page the main Jakarta site. </p> <p> -A very good place to start is by <b>reviewing the list of open issues</b> 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 <b>reviewing the list of open issues</b> 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. </p> <p> -If none of the pending issues scratch your itch, another good place to start is by -<b>contributing unit tests</b> for existing features (even those that still work). +If none of the pending issues scratch your itch, +another good place to start is by <b>contributing unit tests</b> +for existing features (even those that still work). </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). +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-executesthe 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> </section> -<section href="documentation" name="How can I contribute to the documentation?"> +<section href="documentation" + name="How can I contribute to the documentation?"> <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. +source code. +Otherwise, all the same precepts and procedures pertain. </p> <p> -The trick to getting started is to download the nightly build and try -building the documentation WAR. Then try adding your own XML page under doc/ 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 available under target/documentation/. +The trick to getting started is to download the nightly build and try building +the documentation WAR. +Then try adding your own XML page under doc/ 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 available under target/documentation/. </p> <p> -The website portion of the package is the root directory of doc/. The User Guide -portion is under the userGuide/ folder. If the material you'd to add doesn't -fit right in with what's there, the best thing may to start a new section after -the existing material. The navigation column can found in the project.xml document. +The website portion of the package is the root directory of doc/. +The User Guide portion is under the userGuide/ folder. +If the material you'd to add doesn't fit right in with what's there, +the best thing may to start a new section after the existing material. +The navigation column can found in the project.xml document. </p> <p> -To display markup, substitute &lt; for <. The unmatched trailing > will -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/>. +To display markup, substitute &lt; for <. +The unmatched trailing > will 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. +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> @@ -223,133 +266,161 @@ <p> Jakarta products are released the basis of merit, and ~not~ according -to a strict timetable. The volunteers devote whatever time they can to working -the product. But all volunteers have real jobs and real lives, that -do take precedence. Since Struts does not have paid personnel working -the project, we simply cannot make date-oriented commitments. +to a strict timetable. +The volunteers devote whatever time they can to working the product. +But all volunteers have real jobs and real lives, that do take precedence. +Since Struts does not have paid personnel working the project, +we simply cannot make date-oriented commitments. </p> <p> -All Jakarta products must circulate a public beta before release. If a -beta is not in circulation, then it's a good bet that a release is not -forthcoming any time soon. Products sometimes go through several betas -before final release. So if this is beta 1, then it still may not -released any time soon. +All Jakarta products must circulate a public beta before release. +If a beta is not in circulation, +then it's a good bet that a release is not forthcoming any time soon. +Products sometimes go through several betas before final release. +So if this is beta 1, then it still may not released any time soon. </p> <p> -The bottom line is that Jakarta 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. +The bottom line is that Jakarta 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 ;-) +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 private CVS's or private -development lists. What you see is what we got. If you are following the -DEV list, then you know everything the developers know. Really, you do. +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 private CVS's or private development lists. +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> -<i>So, what do you tell your team?</i> If you can ship your application based -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 a release build of -Struts, then you should base your development the release build of Struts, -and keep an eye what is coming down the pipeline. This way you are at least -forewarned and forearmed. +<i>So, what do you tell your team?</i> +If you can ship your application based 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 a release build of Struts, +then you should base your development the release build of Struts, +and keep an eye what is coming down the pipeline. +This way you are at least forewarned and forearmed. </p> </section> -<section href="release_help" name="What can I do to help the next release along?"> +<section href="release_help" + name="What can I do to help the next release along?"> <ul> <li> - Most importantly, <b>download the latest beta</b> or release-candidate and test - it against your own applications. Report any and all issues or suspected issues - to <a href="http://jakarta.apache.org/site/bugs.html";>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 done? -- When we run out - of issues =:o) The sooner we find them, the sooner we are done.) + Most importantly, <b>download the latest beta</b> or release-candidate and + test it against your own applications. + Report any and all issues or suspected issues to + <a href="http://jakarta.apache.org/site/bugs.html";>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 done? -- When we run out of issues =:o) + The sooner we find them, the sooner we are done.) </li> <li> - <b>Contribute <a href="kickstart.html#tests">unit tests</a></b>. The closer we get - to a release, the more we worry about breaking something. The more tests we have, the - more confident we can when applying patches. Tests that proves that a pending - issue is actually a bug are the most welcome. But we are eager for any and all tests - for any and all features, even those that still work =:0). + <b>Contribute <a href="kickstart.html#tests">unit tests</a></b>. + The closer we get to a release, the more we worry about breaking something. + The more tests we have, the more confident we can when applying patches. + Tests that proves that a pending issue is actually a bug are the most + welcome. + But we are eager for any and all tests for any and all features, + even those that still work =:0). </li> <li> - <b>Review the list of issues</b> 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 the - patch your system, report the results, and cast your vote if it works. + <b>Review the list of issues</b> 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 the patch your system, + report the results, and cast your vote if it works. </li> <li> - <b>Confirm an issue's category and status</b>. 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 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. + <b>Confirm an issue's category and status</b>. + 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 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 <b>vote for issues</b> you feel should be handled - first. If an issue on your ballot doesn't include a patch, feel free to try coding - one yourself. (At Jakarta, patches are the only votes that truly count.) Well over - <a href="volunteers.html">thirty developers</a> have contributed code or - documentation to the product. You can too =:0) + first. + If an issue on your ballot doesn't include a patch, feel free to try coding + one yourself. + (At Jakarta, patches are the only votes that truly count.) + Well over <a href="volunteers.html">thirty developers</a> have contributed + code or documentation to the product. + You can too =:0) </li> <li> - <b>Answer questions on the user list.</b> The Committers only have so much time to - volunteer. If Developers are supporting each other on the lists, the - Committers have more time to spend on the next release. + <b>Answer questions on the user list.</b> + The Committers only have so much 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> </section> -<section href="decisions" name="Who makes the final decisions regarding Struts"> +<section href="decisions" + name="Who makes the final decisions regarding Struts"> <p> -The management of the Jakarta site, and the Struts product, is based on principles and -practices used by creators of the Apache HTTPD server. Struts follows the -<a href="http://jakarta.apache.org/site/guidelines.html";>Project Guidelines</a> on the -main Jakarta site. +The management of the Jakarta site, and the Struts product, is based on +principles and practices used by creators of the Apache HTTPD server. +Struts follows the +<a href="http://jakarta.apache.org/site/guidelines.html";>Project Guidelines</a> +on the main Jakarta site. </p> -<p>If you are new to this style of development, the Apache HTTPD Dev list is available in a -<a href="[EMAIL PROTECTED]">digest form</a>. Even if you are not -working on the HTTPD server yourself, it is interesting to watch how the HTTPD team -works on the server. +<p>If you are new to this style of development, +the Apache HTTPD Dev list is available in a +<a href="[EMAIL PROTECTED]">digest form</a>. +Even if you are not working on the HTTPD server yourself, +it is interesting to watch how the HTTPD team works on the server. </p> <p> -The Struts project has its own <a href="using.html#Lists">Dev list</a>, where all of -the decisions regarding Struts are made. Most development takes place via -"<a href="http://jakarta.apache.org/site/proposal.html#decisions/voting/items";>Lazy Consensus</a>". -Committers post most changes to the product unilaterally, using their own best judgment, -and only discuss or vote upon controversial matters. Another Committer can veto any change in an -unreleased product with cause. +The Struts project has its own <a href="using.html#Lists">Dev list</a>, +where all of the decisions regarding Struts are made. +Most development takes place via +"<a href="http://jakarta.apache.org/site/proposal.html#decisions/voting/items";> +Lazy Consensus</a>". +Committers post most changes to the product unilaterally, using their own best +judgment, and only discuss or vote upon controversial matters. +Another Committer can veto any change in an unreleased product with cause. </p> </section>
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
