husted 2004/01/27 02:33:57 Modified: doc/faqs helping.xml Log: Update advice re @author tags. Add more links to patch howtos. Revision Changes Path 1.9 +175 -166 jakarta-struts/doc/faqs/helping.xml Index: helping.xml =================================================================== RCS file: /home/cvs/jakarta-struts/doc/faqs/helping.xml,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- helping.xml 19 Sep 2003 22:09:42 -0000 1.8 +++ helping.xml 27 Jan 2004 10:33:57 -0000 1.9 @@ -14,10 +14,10 @@ <p> -"You can't always get what you want / -but if you try real hard / +"You can't always get what you want / +but if you try real hard / you might just find / -that you get what you need". +that you get what you need". <br/> [Rolling Stones] </p> @@ -48,56 +48,64 @@ <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 +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> -Our challenge to any team using Struts 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="http://jakarta.apache.org/site/bugs.html";>Bugzilla</a> for any issues -without a patch or unit test, +Our challenge to any team using Struts 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="http://jakarta.apache.org/site/bugs.html";>Bugzilla</a> for any issues +without a patch or unit test, and add the patch or test. -If the patch is written on company time, -and you want to give your company an author's credit, that's fine with us. +Please note that Struts does not use @author tags in our JavaDocs. +If your patch includes an @author tag, we would have to ask that it be removed. </p> <p> -If Struts doesn't do what <em>you</em> want, it's up to <strong>you</strong> to step up +(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. +</p> + +<p> +If Struts doesn't do what <em>you</em> want, it's up to <strong>you</strong> 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 +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 +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> -Some Apache products like you to submit your patch to the mailing list. -We would prefer that you create a +Some Apache products like you to submit your patch to the mailing list. +We would prefer that you create a <a href="http://jakarta.apache.org/site/bugs.html";>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, +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 +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> @@ -107,22 +115,22 @@ <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 be sure that an issue is resolved, read +<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 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://jakarta.apache.org/site/bugs.html";><strong>Bugzilla</strong></a>. </p> <p> -Feature requests are also maintained in the Bugzilla database. +Feature requests are also maintained in the Bugzilla database. </p> <p> <a href="http://jakarta.apache.org/site/source.html";>Patches</a> are always -welcome. +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.) @@ -130,7 +138,7 @@ <p> If your bug or feature is already in Bugzilla, <strong>you can vote</strong> -for the issue and call more attention to it. +for the issue and call more attention to it. Each user can cast up to six votes at a time. </p> @@ -138,29 +146,30 @@ 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 add a "works for me" note to a ticket if you've tried the patch yourself +and found it useful. </p> </section> -<section href="contribute" +<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 +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>. +<a href="http://jakarta.apache.org/site/bugs.html";>request new features</a>. Developers can -contribute patches, new code, and documentation. +contribute patches, new code, and documentation. The most active Developers may become -<a href="http://jakarta.apache.org/site/roles.html";>Committers</a>, +<a href="http://jakarta.apache.org/site/roles.html";>Committers</a>, who make the actual decisions about Strut's codebase. </p> @@ -171,21 +180,21 @@ </p> <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, +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. </p> <p> -If none of the pending issues scratch your itch, -another good place to start is by <strong>contributing unit tests</strong> +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> @@ -193,59 +202,59 @@ 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 +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> </section> -<section href="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. +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. +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 be 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 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 be found in the project.xml document. </p> <p> -To display markup, substitute &lt; for <. -The unmatched trailing > will be ignored. -Since it is XML, all elements also need to closed. +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 +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> @@ -264,127 +273,127 @@ <p> Jakarta 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, +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> -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. +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 be 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). +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 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. +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> -<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, +<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. +and keep an eye on what is coming down the pipeline. This way you are at least forewarned and forearmed. </p> </section> -<section href="release_help" +<section href="release_help" name="What can I do to help the next release along?"> <ul> <li> - Most importantly, <strong>download the latest beta</strong> 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're done? -- When we run out of issues =:o) + Most importantly, <strong>download the latest beta</strong> 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'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, + <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, + <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 + <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. + 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. - (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. + 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> - <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, + <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> @@ -392,32 +401,32 @@ </section> -<section href="decisions" +<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 +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="mailto:[EMAIL PROTECTED]">digest form</a>. -Even if you are not working on the HTTPD server yourself, +<p>If you are new to this style of development, +the Apache HTTPD Dev list is available in a +<a href="mailto:[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. +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. +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>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
