Re: Early review of DUCC pre-release - release notes vs readme

[Jaroslaw Cwiklik <ui...@gmail.com>]

I will remove DUCC description from the README.

As far as the RELEASE_NOTES for DUCC, I modeled it on the UIMA
RELEASE_NOTES, which
does have
- How to Get Involved
- How to Report Issues

Should I move these two to README? Or should I keep those in RELEASE_NOTES
to keep it
consistent with UIMA?

With respect to Known Limitations, I will move this to DUCCs RELEASE_NOTES

I would propose to defer handling of a version in both the README and
RELEASE_NOTES till
the next release of DUCC.




On Wed, Nov 27, 2013 at 12:29 PM, Marshall Schor <ms...@schor.com> wrote:

> The criterion of where things go - the README or the RELEASE_NOTES - is
> not clear.
>
> Here are some thoughts on this.
> The README should be general and important information, perhaps not
> changing too
> much from release to release.
>
> It's where new users are likely to read (more likely than they would be to
> read
> the RELEASE_NOTES, I think).
>
> To make it more likely it is "absorbed" by new users, it's important to
> limit
> this to *important* things.
>
> The RELEASE-NOTES is for things that are particular to a release.  It can
> hyperlink to the README.
>
> Currently, DUCC's README and RELEASE-NOTES both have identical paragraphs
> describing what DUCC is.  While this is OK, it might be easier to maintain
> going
> forward if this was just in the README.
>
> The RELEASE_NOTES have some sections it seems to me belong in the readme:
>  how
> to get involved, and how to report issues.
>
> Both of these files have a section which is the high level,  more
> reader-friendly (than the Jira issues list) summary of major changes.  One
> calls
> it "major changes", the other "what's new in release x.y.z".  The one in
> the
> RELEASE_NOTES currently is empty except for a hyperlink to the README one.
>
> This summary of changes section seems to belong to RELEASE_NOTES, unless
>   - they describe changes that cover multiple releases
>   - they're *important* and we want to increase the likelyhood of a
> downloader
> reading them
>
> Known problems and limitations:  this too seems to belong to
> RELEASE_NOTES, unless
>   - they describe problems/limitations that cover multiple releases
>   - they're *important* and we want to increase the likelyhood of a
> downloader
> reading them
>
> Since both of these files have version #s, it would be good to automate the
> insertion of the correct version # into them :-).
>
> -Marshall
>

Re: Early review of DUCC pre-release - release notes vs readme

[Marshall Schor <ms...@schor.com>]

On 12/2/2013 4:22 PM, Jaroslaw Cwiklik wrote:
> I will remove DUCC description from the README.
>
> As far as the RELEASE_NOTES for DUCC, I modeled it on the UIMA
> RELEASE_NOTES, which
> does have
> - How to Get Involved
> - How to Report Issues
>
> Should I move these two to README? Or should I keep those in RELEASE_NOTES
> to keep it
> consistent with UIMA?

I'm fine with either approach, but slightly favor these in README.  The next
release manager might change this for UIMA, too.

>
> With respect to Known Limitations, I will move this to DUCCs RELEASE_NOTES
>
> I would propose to defer handling of a version in both the README and
> RELEASE_NOTES till
> the next release of DUCC.

I think that is perfectly fine.

>
>
>
>
> On Wed, Nov 27, 2013 at 12:29 PM, Marshall Schor <ms...@schor.com> wrote:
>
>> The criterion of where things go - the README or the RELEASE_NOTES - is
>> not clear.
>>
>> Here are some thoughts on this.
>> The README should be general and important information, perhaps not
>> changing too
>> much from release to release.
>>
>> It's where new users are likely to read (more likely than they would be to
>> read
>> the RELEASE_NOTES, I think).
>>
>> To make it more likely it is "absorbed" by new users, it's important to
>> limit
>> this to *important* things.
>>
>> The RELEASE-NOTES is for things that are particular to a release.  It can
>> hyperlink to the README.
>>
>> Currently, DUCC's README and RELEASE-NOTES both have identical paragraphs
>> describing what DUCC is.  While this is OK, it might be easier to maintain
>> going
>> forward if this was just in the README.
>>
>> The RELEASE_NOTES have some sections it seems to me belong in the readme:
>>  how
>> to get involved, and how to report issues.
>>
>> Both of these files have a section which is the high level,  more
>> reader-friendly (than the Jira issues list) summary of major changes.  One
>> calls
>> it "major changes", the other "what's new in release x.y.z".  The one in
>> the
>> RELEASE_NOTES currently is empty except for a hyperlink to the README one.
>>
>> This summary of changes section seems to belong to RELEASE_NOTES, unless
>>   - they describe changes that cover multiple releases
>>   - they're *important* and we want to increase the likelyhood of a
>> downloader
>> reading them
>>
>> Known problems and limitations:  this too seems to belong to
>> RELEASE_NOTES, unless
>>   - they describe problems/limitations that cover multiple releases
>>   - they're *important* and we want to increase the likelyhood of a
>> downloader
>> reading them
>>
>> Since both of these files have version #s, it would be good to automate the
>> insertion of the correct version # into them :-).
>>
>> -Marshall
>>