Yes, I much prefer using markdown for a README file, so it'll be a pleasure to convert it. (I saw only README.txt files in the root folder and a few others, and had incorrectly assumed that the project standard was txt files.) I'll also include the standard ASF license header (which, btw, is also missing from the README.txt files in the root directory and the hbase-examples directory – and perhaps also missing from others).
no standard. just earlier mistakes that we have yet to correct.
Note importantly that the README text I've prepared is directed specifically at the audience of HBase contributors and committers. It gets into the "how-to" of producing new archetypes. The end-user can remain blissfully unaware of all of this; all the end-user will need to do is execute a single Maven command:
mvn archetype:generate -Dfilter=org.apache:hbase
to interactively bring up a list of publicly-available HBase archetypes from which they may choose.
This is part of the confused audience for the reference guide I mentioned earlier. Currently the reference guide has many audiences: downstream application developers, operators, and HBase contributors. It's where our canonical docs live for e.g. making new contributions, building and running tests, etc. Hence both my concern that this will be missed if it is not at all present as well as my concern that the document isn't the best place for all of this.
Regarding end-user documentation, I hope it's okay to leave that to a separate subtask. I would like to successfully get at least one publicly-available archetype loaded into the central Maven archetype directory before finalizing end-user documentation (which will explain to the end-user how to retrieve and use such an archetype). It would potentially sow confusion if we publish the instructions before we finish tinkering around with deployment of our first archetype to make it available.
Yep, definitely fine to make it a follow on subtask. I'd just ask that the task exist prior to this jira getting closed out.
In order to achieve deployment of a new hbase archetype to the Maven central repository, it looks to me like we have to backport the archetype infrastructure (i.e. this patch) to a publicly-available release – at least 1.1.2 (and any other version for which archetypes should be made available) – http://mvnrepository.com/artifact/org.apache.hbase/hbase – Is it correct that we need to do such a backport, or am I missing something?
I originally developed this infrastructure against v1.1.2, so backporting to that version, from my point of view, should be very easy.
The archetypes are a new feature, so they can only be added in a minor version release. we'll probably want to make a separate backport jira to bring this to branch-1. the discussion on dev@hbase should probably include what level of "done" we're looking for before we do that. (as a point of reference, a similar discussion resulted in HBASE-14160 for backporting the hbase-spark module.)