accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ke...@deenlo.com
Subject Re: Review Request 30236: Reorganize README
Date Sat, 31 Jan 2015 01:03:27 GMT


> On Jan. 27, 2015, 8:04 p.m., Christopher Tubbs wrote:
> > TESTING.md, lines 30-32
> > <https://reviews.apache.org/r/30236/diff/5/?file=836999#file836999line30>
> >
> >     `mvn test` doesn't even work in our build, IIRC, due to the multi-module non-jar
dependency for the native-maps. It's probably sufficient to simply suggest `mvn package`,
and note that it executes the maven build lifecycle through unit testing phase.
> 
> kturner wrote:
>     Next patch will have an update related to this.  However I would like you to review
them.  Will leave issue open for now as a reminder.  Can close this after you look at changes.
  Open another issue against new patch if you see more improvements.

`mvn test` does work.  I simplified the instructions there and referenced the surefire plugin.


> On Jan. 27, 2015, 8:04 p.m., Christopher Tubbs wrote:
> > INSTALL.md, lines 152-223
> > <https://reviews.apache.org/r/30236/diff/5/?file=836994#file836994line152>
> >
> >     I would like to see upgrade hints/tips/suggestions/procedures to be documented
in the release notes on the website.
> >     
> >     Perhaps they are appropriate here also, but I feel like those are going to be
very version-specific, and these README files aren't going to get a lot of attention over
time, and this information is going to get stale and/or lengthy and confusing.
> 
> kturner wrote:
>     The instructions will need to be updated for 1.7, could create a follow on issue
about 1.7 upgrade instructions that includes this.  I suppose one option is to not carry these
instructions forward for now, and refer to them in the old README when the 1.7 upgrade instructions
are written.
>     
>     > these README files aren't going to get a lot of attention over time
>     
>     Well I hope this reorganization of the content will encourage maintenance (or no
longer discourage maintenance, as I feel the previous state of things did).  I do not think
docs on the website have a better chance of being maintained vs docs in src.
> 
> Christopher Tubbs wrote:
>     I think the INSTALL.md primary target audience is first-time installers. Upgrade-related
caveats and items to take notice of seem appropriate for the release notes. It's probably
fine to include here as well. I just have more often seen projects provide upgrade instructions/notes
on the website.
>     
>     > I do not think docs on the website have a better chance of being maintained
vs docs in src.
>     
>     In general, I agree. But, that's not the case for release notes... which get attention
on every release.

Dropped the instructions for now and opened [ACCUMULO-3551](https://issues.apache.org/jira/browse/ACCUMULO-3551)


> On Jan. 27, 2015, 8:04 p.m., Christopher Tubbs wrote:
> > BUILD.md, lines 35-71
> > <https://reviews.apache.org/r/30236/diff/5/?file=836993#file836993line35>
> >
> >     I'm not sure this section is even necessary here. It seems more appropriate
to developer documentation on the website.
> 
> kturner wrote:
>     Its useful information, so it needs to go somewhere.  Build instructions for 1.4,
1.5 and 1.6 are very different.  Its nice when dealing with those older versions to be able
to look at their build instructions in the README.  I am not sure if version specific build
instructions would be properly maintained on the website.   IMO keeping these instructions
versioned with source is perferable to putting them on the website.  If we do keep these instructions
in source, I think BUILD.md is an ok place.
> 
> Christopher Tubbs wrote:
>     We have to consider the target audience. For build instructions for the target audience
of "consumers of the source tarball" (the official release), I think the BUILD.md file makes
sense. However, these instructions I've highlighted do not target that audience (as stated
explicitly in the paragraph under the `Iterative Experimentation` header). I think these instructions
would confuse the primary target audience and should not be in the BUILD.md file. It is useful,
though, and we need to put it somewhere... I just think that somewhere should be in a developer
section on the website, rather in the BUILD.md file targeted towards non-developers.

I dropped the instructions and moved contents of BUILD.md to README.md


- kturner


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/30236/#review69865
-----------------------------------------------------------


On Jan. 31, 2015, 12:55 a.m., kturner wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/30236/
> -----------------------------------------------------------
> 
> (Updated Jan. 31, 2015, 12:55 a.m.)
> 
> 
> Review request for accumulo.
> 
> 
> Bugs: ACCUMULO-1515
>     https://issues.apache.org/jira/browse/ACCUMULO-1515
> 
> 
> Repository: accumulo
> 
> 
> Description
> -------
> 
> Reorganized information in README and converted to markdown.  
> 
> At this point I like the INSTALL.md document, but do not really like the content of the
README.md ATM.  Putting this up for review to get suggestions.
> 
> See how the markdown looks on GH : https://github.com/keith-turner/accumulo/tree/ACCUMULO-1515
> 
> 
> Diffs
> -----
> 
>   INSTALL.md PRE-CREATION 
>   NOTICE af212c2 
>   README 4ebb078 
>   README.md PRE-CREATION 
>   TESTING cf2afba 
>   TESTING.md PRE-CREATION 
>   assemble/src/main/assemblies/component.xml 3f18da3 
> 
> Diff: https://reviews.apache.org/r/30236/diff/
> 
> 
> Testing
> -------
> 
> 
> Thanks,
> 
> kturner
> 
>


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