Re: [ALL] Auto generating README.md and CONTRIBUTING.md for github using the commons build plugin

[Benedikt Ritter <br...@apache.org>]

Hello Bernd,

sorry it took so long, I finally have some time to catch up with things...
here are my comments:

2014-08-31 23:20 GMT+02:00 Bernd Eckenfels <ec...@zusammenkunft.net>:

> Hello Benedikt,
>
> I finally had some time to look at this. I tried to integrate it into
> VFS. I did not (yet) change the commpons-parent, I instead used the
> direct call method:
>
> mvn org.apache.commons:commons-build-plugin:1.5-SNAPSHOT:readme-md
>
> I dont think this affects the result substantially, but who knows.
>
> https://github.com/ecki/commons-vfs/tree/draft-readme
>
> Anyway, the things I noticed:
>
> - with VFS beeing a module build where the toplevel is the vfs-project
>   parent, the generated description for the maven artifact might be the
>   wrong one. Is there a plan/option to specify a specific module as the
>   main deliverable?
>

Good point, I haven't thought about multi module builds (yet). There is
currently no way to change the default value (which is the value of the
descirption in the pom). I tried to override project.description via -D but
that wouldn't do the trick...


>
> - in the generated README.md is some html comments about the template
>   system. It talks about "mail-list-template.xml", I guess its a C&P
>   error?
>

I seen that you've already corrected that. Thank you!


>
> - i do like that github is featured, but I wonder if this is true for
>   all commons projects as the prefered way to contribute? Or is this
>   only because you expect README.md to be visible mostly on Github?
>

The latter. My feeling is, that people coming over github don't want to use
our infrastructure (that is ML, SVN and JIRA). IMHO we have two options: 1)
banish them by forcing them to use those tools 2) let them contribute the
way they like and do the necessary stuff, to make the contribution "the
apache way" (create place holder jira issues, bring up important
discussions on the ML).


>
> - the files have been generated with native (windows) CRLF line endings,
>   is that intentional?
>

No idea :o) Are you working on windows? My guess is that the host systems
line endings are used...


>
> - most links relative to project do not work as they use
>   commons-vfs2-project instead of commons-vfs. Do I need to set a
>   property or should the mojo use a different one?
>

If you look at readme-md-template.md the homepage links are generated using
@ARTIFACTID@ placeholder which itself is set to project.artifactId in
generate-xdocs.build.xml. We probably need and additional variable to
handle multi module projects.


>
> - is there suggested javadoc location intended for future use, i.e.
>   should we change the site build of vfs2?
>

No, this is decided on per project basis.


>
> - I wonder can the link from README.md to CONTRIBUTING.md be relative,
>   it somehow has the svn trunk in there.
>

Yep anopther thing that's broken. I don't know whether relative links work.
I do have to play around with that when I have more time.


>
> - for the JIRA link, i think we hava a property for the JIRA project
>   (for the changes report), that can be added to the JIRA URL to be
>   more specific?
>

Yes we have a property, but we only use it on the CONTRIBUTING.md. Should
be changed on README.md.


>
> - I would suggest to name the test command "mvn clean verify" instead
>   of "clean test" to make sure ITs are executed (if present).
>

I've changed the template.


>
> - i wonder if it should not work recursive, the CONTRIBUTING/README in
>   core and examples might not be needed (of course I can skip to commit
>   them).
>

I think CONTRIBUTING and README are only needed on the top-level of the git
repo.

Thanks for all the comments! I don't know when I'll have the time to
implement your suggestions, but feel free to join me :-)


>
> Gruss
> Bernd
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


-- 
http://people.apache.org/~britter/
http://www.systemoutprintln.de/
http://twitter.com/BenediktRitter
http://github.com/britter