struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hus...@apache.org
Subject cvs commit: jakarta-struts/doc/faqs helping.xml
Date Tue, 27 Jan 2004 10:33:58 GMT
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 &quot;meritocracy&quot;, 
  -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 &quot;meritocracy&quot;,
  +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 &amp;lt; for &lt;. 
  -The unmatched trailing > will be ignored. 
  -Since it is XML, all elements also need to closed. 
  +To display markup, substitute &amp;lt; for &lt;.
  +The unmatched trailing > will be ignored.
  +Since it is XML, all elements also need to closed.
   So elements like &lt;br> and &lt;hr> need to set out as &lt;br/> and
&lt;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:dev-digest-subscribe@httpd.apache.org">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:dev-digest-subscribe@httpd.apache.org">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: struts-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: struts-dev-help@jakarta.apache.org


Mime
View raw message