commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernd Eckenfels <e...@zusammenkunft.net>
Subject Re: [ALL] Auto generating README.md and CONTRIBUTING.md for github usingthe commons build plugin
Date Wed, 20 Aug 2014 20:31:25 GMT
Hello, 

sounds good. I wonder if all the parent magic could be avoided by specifying the mojo goal
fully qualified for a stand alone goal. Since you want to commit the result anyway it is not
used so often.

Bernd
-- 
http://bernd.eckenfels.net

----- Ursprüngliche Nachricht -----
Von: "Benedikt Ritter" <britter@apache.org>
Gesendet: ‎20.‎08.‎2014 11:55
An: "Commons Developers List" <dev@commons.apache.org>
Betreff: [ALL] Auto generating README.md and CONTRIBUTING.md for github usingthe commons build
plugin

Hi all,

I've committed a new mojo to the commons build plugin, which generates a
README.md file for a component [1]. README.md files are used by github to
create some kind of a landing page, when you browse a repository. It makes
a repository more inviting to people using github, so I consider it an
asset for attracting new contributors.
In the past I've created these files by hand, but this is becoming
crumbersome. That's why I've added the new mojo.

I've created a fork of [csv] to give you an impression of how the generated
README.md will look like [2]. You can try the mojo out yourself, by
following these steps:

- checkout the commons-build-plugin from
https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk
- mvn install the plugin
- checkout the commons parent pom from
https://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk
- change commons-parent to use commons-build-plugin:1.5-SNAPSHOT
- mvn install commons-parent
- change your component's pom to use commons-parent:35-SNAPSHOT
- call mvn commons:readme-md

One thing we should consider is to create an additional template for a
CONTRIBUTION.md. If a github repo has such a file, it will be displayed to
potential contributors. You can learn more about this here [3]. An example
for a good CONTRIBUTION.md can be found here [4].

The README.md would be regenerated for each release, since it contains the
maven coords. The CONTRIBUTION.mb only needs to be created once or when our
contribution guidelines change (which in turn would require a new release
of the build pluing with the new template).

If nobody has objections, I'll add a mojo for generating a CONTRIBUTION.md
and then start the release process for a new version of
commons-build-plugin.

Regrads,
Benedikt

[1] http://svn.apache.org/r1619060
[2] https://github.com/britter/commons-csv/tree/readme-md-mojo-test
[3] https://github.com/blog/1184-contributing-guidelines
[4] https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md

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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message