You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@tomcat.apache.org by charlie arehart <ch...@carehart.org> on 2018/03/30 16:49:34 UTC
on getting started contributing doc improvements (was RE: On Tomcat 8.5.16, RemoteHostFilter ...)
Pardon the top-posting, but I wanted to take André's helpful reply about getting started in contributing doc improvements (below) and then respond to/expand upon it.
Since it really is an entirely different subject than the OP's intent for the original thread, I have started this new one. (And this is my first time changing the subject line like that, mid-discussion, here on this list. So if that’s wrong either technically or per community standards, just let me know.)
So first, here is what André had written to me, for context, then my reply is below.
> -----Original Message-----
> From: André Warnier (tomcat) <aw...@ice-sa.com>
> Subject: Re: On Tomcat 8.5.16, RemoteHostFilter throwing ServletException the property [allow] is not defined
>
> On 29.03.2018 23:36, charlie arehart wrote:
> > (And as I said in another thread, I don't propose these changes as if
> > to say to someone, "now go do it". I'm saying it as someone who would
> > try to step in and help, if permitted.)
>
> I think that you can do that.
> Have a look here :
> http://tomcat.apache.org/getinvolved.html
> You have already done the first step.
> You can do the second step, whenever you want : if you see a question to which you can contribute a useful response, please do.
> The next step would be the FAQ or Wiki. That's also fairly easy : go to https://wiki.apache.org/tomcat/FrontPage
> and see the "If you do decide to contribute," paragraph.
> (You could for example start by providing some additional examples, as a FAQ article. And I am sure that with a simple request on this list, a link to that FAQ could then be easily added to the main docs).
> If you want to contribute directly by improving the docs, that gets a bit more involved, because it requires downloading the code, submitting patches etc. But it can be done (I did it once, at a time when I wasn't even sure what "diff" meant).
> That will lead you here : http://www.apache.org/dev/contributors.html
> (Note: the process for the documentation is exactly the same as for the code; and as a contribution, it will be appreciated in the same way - or even more, considering the inherent aversion of programmers toward documentation..) And the ultimate reward (after a few years of hard and consciencious work) would be here :
> http://tomcat.apache.org/whoweare.html
>
Thanks very much for all that, André, and I have already started reading all the content about "the process". :-) A couple things flow from your suggestions there.
1) If you (or anyone following along and responsible for that FrontPage) are open to more feedback, your second step pointed me to the section there about, "If you do decide to contribute". The next words there say "you will need to create a Wiki login name", but it doesn't say how to do that. Now, sure, one might figure it out by thinking to click the login button at the top of the page, which then offers a link to create one. But it could be quite helpful if it just went ahead and offered that link under those words "create a Wiki login name", going to https://wiki.apache.org/tomcat/FrontPage?action=newaccount. :-)
2) Anyway, I did that, and the sentence then goes on to say that we should then send that new login name to the dev or users list, asking to be added to the ContributorsGroup. Now, I realize I should (and will) join the dev list also, but since the discussion has started here and may seem to come "out of left field" from me there, I will offer here that the login name is CharlieArehart. Let me know, folks involved, if you prefer I share that on the dev list instead for some reason (in which case, maybe that wording that says "or Tomcat Users" should be removed). As always, I'm just trying to help, not to criticize.
3) And to your final points, yep, I would be only interested in contributing to the docs (and happily) but not code. I truly am just a user of Tomcat--and other Java app servers. Though I've helped people troubleshoot issues with them for 10+ years, I've not written a line of production Java code since before then, so I won't be nearly as helpful with that!
And I do see (from Mark's link to the doc repo, in another doc-related thread yesterday) that the project uses SVN. I'll start getting my head back into that (vs Git) in the meantime. :-)
4) Finally, thanks for the link to the whoweare page. That was helpful. I see now that you and Mark, who had been contributing on this thread, as well as you both and Christopher and Felix who were participating in my other thread about doc contribution, are all committers. Thanks very much for all you guys (and others here) do. Again, I just want to help, as a long-time user.
I'm also a voracious reader of docs, and love to help others leverage them, and so I do often see opps for improvement in them. Of course, I appreciate that not every suggestion would be universally appreciated, and so I trust that the committers would help temper my enthusiasm where needed, such that I remain "more helpful than not". :-)
Looking forward to getting involved.
/charlie
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org
Re: on getting started contributing doc improvements (was RE: On
Tomcat 8.5.16, RemoteHostFilter ...)
Posted by "André Warnier (tomcat)" <aw...@ice-sa.com>.
On 30.03.2018 18:49, charlie arehart wrote:
> 3) And to your final points, yep, I would be only interested in contributing to the docs (and happily) but not code. I truly am just a user of Tomcat--and other Java app servers. Though I've helped people troubleshoot issues with them for 10+ years, I've not written a line of production Java code since before then, so I won't be nearly as helpful with that!
Sounds like we could create a sub-group with just the two of us.
My own speciality area is more in the Apache/mod_perl/perl realm, full-text search engines
and electronic document processing.. and documentation.
I only ended up on this project and list, because I needed tomcat occasionally in my line
of work, and I really liked the spirit and quality of this tomcat user's list (and it's
very low level of noise). So I got hooked.
Contributing Java code to tomcat is certainly beyond my capacity, so I try to be useful by
cherry-picking some slightly out-of-topic questions on this list, and in that way trying
to free some time for the real java/tomcat specialists here, for them to deal with more
pointy issues. But this must have been recognised as a useful contribution, since I was
made a committer some time ago, and I haven't been fired yet.
All this to say that there are many ways to contribute usefully, and not only in code.
And thus, welcome to the team.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org
Re: on getting started contributing doc improvements (was RE: On
Tomcat 8.5.16, RemoteHostFilter ...)
Posted by Konstantin Kolinko <kn...@gmail.com>.
2018-03-30 19:49 GMT+03:00 charlie arehart <ch...@carehart.org>:
>
> 1) If you (or anyone following along and responsible for that FrontPage) are open to more feedback, your second step pointed me to the section there about, "If you do decide to contribute". The next words there say "you will need to create a Wiki login name", but it doesn't say how to do that. Now, sure, one might figure it out by thinking to click the login button at the top of the page, which then offers a link to create one. But it could be quite helpful if it just went ahead and offered that link under those words "create a Wiki login name", going to https://wiki.apache.org/tomcat/FrontPage?action=newaccount. :-)
I updated the Front Page by adding some words, and also fixed Tomcat logo image.
> 2) Anyway, I did that, and the sentence then goes on to say that we should then send that new login name to the dev or users list, asking to be added to the ContributorsGroup. Now, I realize I should (and will) join the dev list also, but since the discussion has started here and may seem to come "out of left field" from me there, I will offer here that the login name is CharlieArehart.
Welcome!
I see that Christopher have already added you.
Regarding the documentation, I think the first step is to get familiar
with how the docs are built.
There is
http://tomcat.apache.org/bugreport.html#How_to_submit_patches_and_enhancement_requests
-> "To prepare a documentation patch..."
The source code for Tomcat can be taken from SVN or from a Git mirror.
It does not matter which one is used as long as you are not trying to
commit it. Either tool or just Unix "diff -u" can be used to create a
patch.
The source code for "tomcat.apache.org" site is only in SVN.
SVN commands can be used to checkout only relevant portion of the site
(skipping megabytes of documentaion/Javadoc for all releases of
Tomcat)
There is a Readme,
https://svn.apache.org/repos/asf/tomcat/site/trunk/README.txt
Best regards,
Konstantin Kolinko
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org
Re: on getting started contributing doc improvements (was RE: On
Tomcat 8.5.16, RemoteHostFilter ...)
Posted by Konstantin Kolinko <kn...@gmail.com>.
2018-03-30 20:16 GMT+03:00 Christopher Schultz <ch...@christopherschultz.net>:
>
> IMHO, the wiki isn't a great place to do ... anything, really. We have
> a few pages that grew and grew (like the FAQ/HOWTO pages) and that's
> all there really is.
>
> I think it would be better to re-organize that information into a
> better format. I'm not entirely sure what that better format might be.
The "FAQ", "HowTo" and "Specification" pages have external links
pointing to them
at tomcat.apache.org site and also in web applications bundled with
released versions of Tomcat (docs, ROOT).
The rest of pages can be moved.
Technically, specific FAQ answers are frequently mentioned in e-mails
and can be found in archives of the mailing lists.
I think that main headache for FAQ and HowTo is to keep them
up-to-date and relevant. I reviewed and updated many of them several
years ago, but a lot of those are rather old. I reorganized HowTo page
several years ago by grouping them into topics.
Best regards,
Konstantin Kolinko
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org
Re: on getting started contributing doc improvements (was RE: On
Tomcat 8.5.16, RemoteHostFilter ...)
Posted by Christopher Schultz <ch...@christopherschultz.net>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
Charlie,
On 3/30/18 12:49 PM, charlie arehart wrote:
> 1) If you (or anyone following along and responsible for that
> FrontPage) are open to more feedback, your second step pointed me
> to the section there about, "If you do decide to contribute". The
> next words there say "you will need to create a Wiki login name",
> but it doesn't say how to do that. Now, sure, one might figure it
> out by thinking to click the login button at the top of the page,
> which then offers a link to create one. But it could be quite
> helpful if it just went ahead and offered that link under those
> words "create a Wiki login name", going to
> https://wiki.apache.org/tomcat/FrontPage?action=newaccount. :-)
Sounds like a reasonable improvement.
> 2) Anyway, I did that, and the sentence then goes on to say that
> we should then send that new login name to the dev or users list,
> asking to be added to the ContributorsGroup. Now, I realize I
> should (and will) join the dev list also, but since the discussion
> has started here and may seem to come "out of left field" from me
> there, I will offer here that the login name is CharlieArehart.
> Let me know, folks involved, if you prefer I share that on the dev
> list instead for some reason (in which case, maybe that wording
> that says "or Tomcat Users" should be removed). As always, I'm just
> trying to help, not to criticize.
Added. You should be able to "contribute" to the wiki, now.
IMHO, the wiki isn't a great place to do ... anything, really. We have
a few pages that grew and grew (like the FAQ/HOWTO pages) and that's
all there really is.
I think it would be better to re-organize that information into a
better format. I'm not entirely sure what that better format might be.
> 3) And to your final points, yep, I would be only interested in
> contributing to the docs (and happily) but not code. I truly am
> just a user of Tomcat--and other Java app servers. Though I've
> helped people troubleshoot issues with them for 10+ years, I've not
> written a line of production Java code since before then, so I
> won't be nearly as helpful with that!
You'll still need to get the source from Subversion[1] or Git[2], make
edits, and submit patches/pull requests. While it's fine to post to
the list and say "on this page there is a missing 'm'", it's not okay
to say "you should re-word these paragraphs to say this:" and then
post a whole bunch of text. A patch/PR is the way to do that.
> And I do see (from Mark's link to the doc repo, in another
> doc-related thread yesterday) that the project uses SVN. I'll
> start getting my head back into that (vs Git) in the meantime. :-)
You can still use Git. See [2].
> 4) Finally, thanks for the link to the whoweare page. That was
> helpful. I see now that you and Mark, who had been contributing on
> this thread, as well as you both and Christopher and Felix who
> were participating in my other thread about doc contribution, are
> all committers. Thanks very much for all you guys (and others here)
> do. Again, I just want to help, as a long-time user.
>
> I'm also a voracious reader of docs, and love to help others
> leverage them, and so I do often see opps for improvement in them.
> Of course, I appreciate that not every suggestion would be
> universally appreciated, and so I trust that the committers would
> help temper my enthusiasm where needed, such that I remain "more
> helpful than not". :-)
>
> Looking forward to getting involved.
Welcome to the community.
- -chris
[1] https://tomcat.apache.org/svn.html
[2] https://tomcat.apache.org/svn.html#Git_Mirror
-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - http://gpgtools.org
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
iQIzBAEBCAAdFiEEMmKgYcQvxMe7tcJcHPApP6U8pFgFAlq+cPMACgkQHPApP6U8
pFg/DRAAw7Y620lOY6LiKGwh5BSIt8AHOudWLmL4JY9RrKWxu2OlPt5deSQPVl5q
2d/rA+GFOqW4JlFHewq1+g9UmAXo+ys2GyG8rijO4ESP45puLm404jYzCff4C+sh
s6FFMYxcUPyGPGfHAT7+IvgIKVagxNb+aZ+M40YFrlHUFO4HFQzRP4EcZcTJFoIa
iSGJLJDalJEWafRv5+bOYjcHGb6IjjRMp/ifC5rvH8AeOLRo3tZK/+MuTVS47S+4
px+IZ4YUMpKuJ+jt9SjFrt7FmfNU5xJxuzrYwluPxnHSbxJ72ECVEUYSCKVNCkup
DZVI1euL7n+eMvnlERWwrTZbYgVMG9YakXMK+wPa3V1E1YZuj2pDETZH5qSlneq9
gnjLFgFTs/hPMIx46iqpw3X2sSntZNpUVZx5AHfloOGCiNsQ41zuzpMF6C0NcgXX
UfaQLmDzso53qb0wHZ+33svSYv/P/+DyRc7yZ9WsSNVwfaqexa2re0dVrBM+iy5A
dFH0YOW1qFhZeU9xXaeNBlkMBESrNrrYaf9PhBMVC+KcGIzb2mxKtFU9RJW49PKi
KI8u8cc8DbIQ3VlCC6a4fwWwNKCENrGkNGzgqMLWnlFlH76ma6CV0EKc0IoUNM0h
wt4R6LYPZ2Q7khPCKXf684U1q1eH1XuSotaKK4gqiUkedy3xZTU=
=4CWW
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org