You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Lukasz Lenart <lu...@apache.org> on 2013/09/04 11:06:11 UTC

How to contribute

I have changed title to not interfere with the main topic

2013/9/4 Christian Grobmeier <gr...@gmail.com>:

> We just need to know that potential Struts committers already have more
> barriers than the average GitHub user. At least when the ICLA is on file
> we need to make it as easy as possible to contribute. Compared to all
> other projects I know at the ASF I think its pretty difficult to
> contribute Struts

Could you elaborate a bit more? How can we improve that?


Thanks in advance
-- 
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: How to contribute

Posted by Lukasz Lenart <lu...@apache.org>.
One more general comment - we should start throwing away some outdated
docs i.e. the old tutorials

http://struts.apache.org/development/2.x/docs/bootstrap.html


Regards
-- 
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: How to contribute

Posted by Christian Grobmeier <gr...@gmail.com>.
Am 05.09.13 07:51, schrieb Lukasz Lenart:
> Argh.....
:-)
> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>> When I first looked at Struts, the website was a mess. It still is (but
>> we're working on it). I was confused by countless topics. It is in my
>> genes to look at the source code immediately, but the Struts sources
>> were huge. Unfortunately i was not able to connect documentation to the
>> source code.
> Sometime ago someone did start working on the new User Guide
>
> http://struts.apache.org/development/2.x/docs/user-guide.html
I think this is a great TOC already. If it would be finished, we would
have a huge win!

>> Then I found some docs in the wiki. But the correlation of Struts
>> documentation to the wiki and static webpages is black magic. Honestly,
>> if I couldn't ask you (Lukasz) I would still not know how these things
>> are all tied. And believe me, I am going to continue to ask you on it.
> There is no correlation :-) Basically what is under /docs is exported
> from Confluence /WW - so we have a dualism here ;-)
> It would be cool to have everything in one place - webpage and docs
> either in Confluence or as webpages (i.e. Markdown)
As you know, we have hacked on Struts past weekend. We discussed docs
and well, it was a pain point for a lot of them. When we elaborated
further we formed some kind of a plan.

First off, I fully agree - everything should be on one place. Personally
I prefer to use Markdown and would like to avoid Confluence as much as
possible. I don't like the idea to be tied to a commercial product with
one of the most important assets we have - the docs.

now, what if we would have all of our docs integrated in "mvn site"?
Imagine the following scenario:

- mvn site
- our Struts-Create-Snippets maven plugin walks the source code, creates
snippets from javadoc to /target
- the Struts-Replace-Snippets maven plugin copies the markdown, then
repalces the snippets previously generated
- then the usual site process

This would more or less allow to remove the cxf plugin dependency, opt
out of Confluence and integrate site building to our usual lifecycle.

We already started some effort on Saturday - well, in fact Andreas
Prüller did. You can see some starting points here:
https://github.com/opensourceio/struts-maven-plugins

Andreas has an ICLA on file and wants to contribute to this - i put him
on CC, just in case he did not subscribe already.

The plan is, we collaborate further on GitHub as Andreas has write
access there and the officially donate it to Struts.

What do you think about this?



>
>> This is a huge help for others:
>> http://struts.apache.org/helping.html
>>
>> But I believe given our huge website its hard to find. It says how I
>> create a patch and how join the mailing list. But thats not enough in
>> the Struts case. I would love detailled, easy to understand instructions
>> how a non-committer can fix typos on our docs in less then a minute. I
>> mean instructions which you don't need to search. I think we'll need to
>> explain how we are building things.
> Many of the informations are outdated and can overwhelm users - I
> don't like to read half of page to at the end perform mvn
> release:perform ;-)
>
> I mostly like our release guideline, yet still outdated but it tells
> you step-by-step what to do. 'Why' is less important on the beginning.
>
> http://struts.apache.org/development/2.x/docs/building-struts-2-normal-release.html
>
This is fantastic. I think we should include it in an improved part of
the struts main page.
>> I think we should make things like
>> this page:
>>
>> https://cwiki.apache.org/confluence/display/WW/Struts+Next
>>
>> more prominent. We should also explain what we would do when we start
>> working on v2.5 (do we create a branch? do we just commit to the trunk?
>> and so on).
> There is one problem with that - why did you ask beforehand? If you
> don't know something, please ask - then I can answer or update docs or
> something else. The main problem here is I don't know if something is
> missing, for me some informations are obvious. To be more specific and
> answer your question: we will figure it out and discuss when we will
> switch to Git and start working on 2.5.
>
> I don't like to prepare huge plans for the future - be agile, adjust,
> change, go ahead ;-)
hehe :-) Be assured, I am asking when I am not understanding.
My point was: others, non-committers might be overwhelmed. While
I agree we need to be agile, we should document our usual development
workflow. I found some parts were already done, so maybe its just compiling
it and put it to a better place. I am willing to go forward with this, i
think its then easiert ot understand if there is something to read.

>> When I go to Commons I don't have such problems. I check out a small
>> component and send in a patch. If I am doing it wrong, somebody tells
>> me. But in Struts land everything is so huge.
>>
>> For me it is all with a better documented workflow and better websites.
> Good point! Is http://struts.apache.org/helping.html worth
> extending/simplifying and exposing on the main page?
Absolutely!

I will write a new message in a minute, but I have already worked on
this today.
I like it much and believe the whole section could address all of my
pain points I mentioned
and increase the contributions.

I ahve already started with giving some love to it on a branch and plan
to prepare some first
git documents for it too.

Cheers + Thnks!

>
> Regards


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: How to contribute

Posted by Lukasz Lenart <lu...@apache.org>.
Argh.....

2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> When I first looked at Struts, the website was a mess. It still is (but
> we're working on it). I was confused by countless topics. It is in my
> genes to look at the source code immediately, but the Struts sources
> were huge. Unfortunately i was not able to connect documentation to the
> source code.

Sometime ago someone did start working on the new User Guide

http://struts.apache.org/development/2.x/docs/user-guide.html

> I started with the JSON plugin first and got this:
> http://struts.apache.org/release/2.3.x/struts2-plugins/struts2-json-plugin/index.html
>
> which is an empty page. I looked into the source code and was not
> quickly able to find out whats going on.
>
> Then I found some docs in the wiki. But the correlation of Struts
> documentation to the wiki and static webpages is black magic. Honestly,
> if I couldn't ask you (Lukasz) I would still not know how these things
> are all tied. And believe me, I am going to continue to ask you on it.

There is no correlation :-) Basically what is under /docs is exported
from Confluence /WW - so we have a dualism here ;-)
It would be cool to have everything in one place - webpage and docs
either in Confluence or as webpages (i.e. Markdown)

> This is a huge help for others:
> http://struts.apache.org/helping.html
>
> But I believe given our huge website its hard to find. It says how I
> create a patch and how join the mailing list. But thats not enough in
> the Struts case. I would love detailled, easy to understand instructions
> how a non-committer can fix typos on our docs in less then a minute. I
> mean instructions which you don't need to search. I think we'll need to
> explain how we are building things.

Many of the informations are outdated and can overwhelm users - I
don't like to read half of page to at the end perform mvn
release:perform ;-)

I mostly like our release guideline, yet still outdated but it tells
you step-by-step what to do. 'Why' is less important on the beginning.

http://struts.apache.org/development/2.x/docs/building-struts-2-normal-release.html

> I think we should make things like
> this page:
>
> https://cwiki.apache.org/confluence/display/WW/Struts+Next
>
> more prominent. We should also explain what we would do when we start
> working on v2.5 (do we create a branch? do we just commit to the trunk?
> and so on).

There is one problem with that - why did you ask beforehand? If you
don't know something, please ask - then I can answer or update docs or
something else. The main problem here is I don't know if something is
missing, for me some informations are obvious. To be more specific and
answer your question: we will figure it out and discuss when we will
switch to Git and start working on 2.5.

I don't like to prepare huge plans for the future - be agile, adjust,
change, go ahead ;-)

> When I go to Commons I don't have such problems. I check out a small
> component and send in a patch. If I am doing it wrong, somebody tells
> me. But in Struts land everything is so huge.
>
> For me it is all with a better documented workflow and better websites.

Good point! Is http://struts.apache.org/helping.html worth
extending/simplifying and exposing on the main page?


Regards
-- 
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: How to contribute

Posted by Lukasz Lenart <lu...@apache.org>.
Sorry for the first answer .... new GMail UI :\

2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> When I first looked at Struts, the website was a mess. It still is (but
> we're working on it). I was confused by countless topics. It is in my
> genes to look at the source code immediately, but the Struts sources
> were huge. Unfortunately i was not able to connect documentation to the
> source code.

Sometime ago someone did start a new User Guide



>
> I started with the JSON plugin first and got this:
> http://struts.apache.org/release/2.3.x/struts2-plugins/struts2-json-plugin/index.html
>
> which is an empty page. I looked into the source code and was not
> quickly able to find out whats going on.
>
> Then I found some docs in the wiki. But the correlation of Struts
> documentation to the wiki and static webpages is black magic. Honestly,
> if I couldn't ask you (Lukasz) I would still not know how these things
> are all tied. And believe me, I am going to continue to ask you on it.
>
> This is a huge help for others:
> http://struts.apache.org/helping.html
>
> But I believe given our huge website its hard to find. It says how I
> create a patch and how join the mailing list. But thats not enough in
> the Struts case. I would love detailled, easy to understand instructions
> how a non-committer can fix typos on our docs in less then a minute. I
> mean instructions which you don't need to search. I think we'll need to
> explain how we are building things. I think we should make things like
> this page:
>
> https://cwiki.apache.org/confluence/display/WW/Struts+Next
>
> more prominent. We should also explain what we would do when we start
> working on v2.5 (do we create a branch? do we just commit to the trunk?
> and so on).
>
> When I go to Commons I don't have such problems. I check out a small
> component and send in a patch. If I am doing it wrong, somebody tells
> me. But in Struts land everything is so huge.
>
> For me it is all with a better documented workflow and better websites.
>
> Hopefully others, non-committers now put some ideas in here!
>
> Cheers
> Christian
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>

http://struts.apache.org/development/2.x/docs/user-guide.html

-- 
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: How to contribute

Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> Am 04.09.13 11:06, schrieb Lukasz Lenart:
>> I have changed title to not interfere with the main topic
> Thanks!
>> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>>
>>> We just need to know that potential Struts committers already have more
>>> barriers than the average GitHub user. At least when the ICLA is on file
>>> we need to make it as easy as possible to contribute. Compared to all
>>> other projects I know at the ASF I think its pretty difficult to
>>> contribute Struts
>> Could you elaborate a bit more? How can we improve that?
>>
> Sure. Hopefully others who are not familiar with the ASF in general will
> speak up to.
>
> When I first looked at Struts, the website was a mess. It still is (but
> we're working on it). I was confused by countless topics. It is in my
> genes to look at the source code immediately, but the Struts sources
> were huge. Unfortunately i was not able to connect documentation to the
> source code.
>
> I started with the JSON plugin first and got this:
> http://struts.apache.org/release/2.3.x/struts2-plugins/struts2-json-plugin/index.html
>
> which is an empty page. I looked into the source code and was not
> quickly able to find out whats going on.
>
> Then I found some docs in the wiki. But the correlation of Struts
> documentation to the wiki and static webpages is black magic. Honestly,
> if I couldn't ask you (Lukasz) I would still not know how these things
> are all tied. And believe me, I am going to continue to ask you on it.
>
> This is a huge help for others:
> http://struts.apache.org/helping.html
>
> But I believe given our huge website its hard to find. It says how I
> create a patch and how join the mailing list. But thats not enough in
> the Struts case. I would love detailled, easy to understand instructions
> how a non-committer can fix typos on our docs in less then a minute. I
> mean instructions which you don't need to search. I think we'll need to
> explain how we are building things. I think we should make things like
> this page:
>
> https://cwiki.apache.org/confluence/display/WW/Struts+Next
>
> more prominent. We should also explain what we would do when we start
> working on v2.5 (do we create a branch? do we just commit to the trunk?
> and so on).
>
> When I go to Commons I don't have such problems. I check out a small
> component and send in a patch. If I am doing it wrong, somebody tells
> me. But in Struts land everything is so huge.
>
> For me it is all with a better documented workflow and better websites.
>
> Hopefully others, non-committers now put some ideas in here!
>
> Cheers
> Christian
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>



-- 
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: How to contribute

Posted by Christian Grobmeier <gr...@gmail.com>.
Am 04.09.13 11:06, schrieb Lukasz Lenart:
> I have changed title to not interfere with the main topic
Thanks!
> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>
>> We just need to know that potential Struts committers already have more
>> barriers than the average GitHub user. At least when the ICLA is on file
>> we need to make it as easy as possible to contribute. Compared to all
>> other projects I know at the ASF I think its pretty difficult to
>> contribute Struts
> Could you elaborate a bit more? How can we improve that?
>
Sure. Hopefully others who are not familiar with the ASF in general will
speak up to.

When I first looked at Struts, the website was a mess. It still is (but
we're working on it). I was confused by countless topics. It is in my
genes to look at the source code immediately, but the Struts sources
were huge. Unfortunately i was not able to connect documentation to the
source code.

I started with the JSON plugin first and got this:
http://struts.apache.org/release/2.3.x/struts2-plugins/struts2-json-plugin/index.html

which is an empty page. I looked into the source code and was not
quickly able to find out whats going on.

Then I found some docs in the wiki. But the correlation of Struts
documentation to the wiki and static webpages is black magic. Honestly,
if I couldn't ask you (Lukasz) I would still not know how these things
are all tied. And believe me, I am going to continue to ask you on it.

This is a huge help for others:
http://struts.apache.org/helping.html

But I believe given our huge website its hard to find. It says how I
create a patch and how join the mailing list. But thats not enough in
the Struts case. I would love detailled, easy to understand instructions
how a non-committer can fix typos on our docs in less then a minute. I
mean instructions which you don't need to search. I think we'll need to
explain how we are building things. I think we should make things like
this page:

https://cwiki.apache.org/confluence/display/WW/Struts+Next

more prominent. We should also explain what we would do when we start
working on v2.5 (do we create a branch? do we just commit to the trunk?
and so on).

When I go to Commons I don't have such problems. I check out a small
component and send in a patch. If I am doing it wrong, somebody tells
me. But in Struts land everything is so huge.

For me it is all with a better documented workflow and better websites.

Hopefully others, non-committers now put some ideas in here!

Cheers
Christian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org