commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benedikt Ritter <brit...@apache.org>
Subject [ALL] Auto generating README.md and CONTRIBUTING.md for github using the commons build plugin
Date Wed, 20 Aug 2014 09:55:51 GMT
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