[prev in list] [next in list] [prev in thread] [next in thread]
List: solr-dev
Subject: Re: SOLR: Why do we have a CHANGES.txt/md to maintain?
From: David Smiley <dsmiley () apache ! org>
Date: 2020-11-30 14:04:21
Message-ID: CABEwPvGrrT-rjstfGnRMB1LmLXSYXbXipAwXQym2kX5hUO3jNw () mail ! gmail ! com
[Download RAW message or body]
I get your point on different audiences... sometimes I peer-review us on
dubiously written CHANGES.txt entries to be more user friendly. However,
this attention could and should be given to JIRA issue summaries as well.
We all benefit from that. Also, for Solr in particular, the need for
examining CHANGES / JIRA is reduced because we have a solr-upgrade-notes.adoc
which is editorialized and covers just the important stuff; no minor
matters. We link to this from release announcements.
~ David Smiley
Apache Lucene/Solr Search Developer
http://www.linkedin.com/in/davidwsmiley
On Mon, Nov 30, 2020 at 3:29 AM Adrien Grand <jpountz@gmail.com> wrote:
> I have a preference for maintaining a separate CHANGES file because it
> allows us to keep JIRA focused for a committer/contributor audience while
> the CHANGES file can describe changes that matter for users. Elasticsearch
> uses a similar mechanism for release notes to what you are proposing, using
> GitHub instead of JIRA. It works well, but in my opinion the Lucene/Solr
> process produces better curated release notes.
>
> On Mon, Nov 30, 2020 at 12:25 AM David Smiley <dsmiley@apache.org> wrote:
>
>> Well the commit history remains there as well and was converted from SVN
>> and may eventually be converted to something else. My point is that it has
>> been retained. On release boundaries, we could not only distribute
>> Changes.html (a JIRA export) in the assembly (tar.gz) but we could also
>> commit it to source control on each release branch, and thus will transfer
>> along with source control into the future, which is way more convenient
>> than digging up an old binary.
>>
>> ~ David Smiley
>> Apache Lucene/Solr Search Developer
>> http://www.linkedin.com/in/davidwsmiley
>>
>>
>> On Sun, Nov 29, 2020 at 5:55 AM Dawid Weiss <dawid.weiss@gmail.com>
>> wrote:
>>
>>> Changes in the repository stay there forever (think
>>> cvs/svn/git/whatever comes next...). External tools change all the
>>> time. This is the benefit I see.
>>>
>>> Dawid
>>>
>>> On Sun, Nov 29, 2020 at 6:32 AM David Smiley <dsmiley@apache.org> wrote:
>>> >
>>> > After recently proposing per-module CHANGES.md... I think I'd actually
>>> rather not have any CHANGES file at all to maintain. I'd rather go to JIRA
>>> with a bit better hygiene for metadata like components==contrib/module, and
>>> have some convenient links sprinkled about so that it's a convenient click
>>> away from each module. This proposal may not be as compelling for Lucene
>>> which has no solr-upgrade-notes.adoc file.
>>> >
>>> > Maintaining this CHANGES file (or files) is a pain. Formatting it
>>> just-so & conversion to HTML & other scripts manipulating it in dev-tools
>>> (e.g. add version), and branch syncing. It's commonly a source of merge
>>> conflicts more than any other file. It's an annoying step with GitHub PRs
>>> in particular. Why do we bother? Instead, on releases, provide a JIRA
>>> link to display all fixed issues grouped by issue type. We could export it
>>> to a file for direct inclusion in the distribution. JIRA even has a
>>> feature for this -- here's a direct link for 8.7:
>>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12310230&version=12348463
>>> Notice the HTML version at the bottom. It could be dumped into the release
>>> binaries.
>>> > Issue summaries tend to be much shorter than CHANGES.txt bullets but I
>>> think that's okay because it's not the only information available for those
>>> who want to know more. Remember there is also all the other metadata in
>>> JIRA a user can examine, there are commit messages, sometimes PRs, and
>>> there's solr-upgrade-notes.adoc which ought to be the starting point for
>>> someone interested in a release.
>>> >
>>> > It's been argued that contributors should get attribution here but we
>>> could maintain a separate contributors file to acknowledge people by name
>>> for inclusion with the Solr distribution -- one that has a link to JIRA and
>>> GitHub even.
>>> >
>>> > ~ David Smiley
>>> > Apache Lucene/Solr Search Developer
>>> > http://www.linkedin.com/in/davidwsmiley
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>>> For additional commands, e-mail: dev-help@lucene.apache.org
>>>
>>>
>
> --
> Adrien
>
[Attachment #3 (text/html)]
<div dir="ltr"><div dir="ltr">I get your point on different audiences... sometimes I \
peer-review us on dubiously written CHANGES.txt entries to be more user friendly. \
However, this attention could and should be given to JIRA issue summaries as well. \
We all benefit from that. Also, for Solr in particular, the need for examining \
CHANGES / JIRA is reduced because we have a <span \
style="color:rgb(0,0,0)">solr-upgrade-notes.adoc which is editorialized and covers \
just the important stuff; no minor matters. We link to this from release \
announcements.</span><div><br clear="all"><div><div dir="ltr"><div dir="ltr">~ David \
Smiley<div>Apache Lucene/Solr Search Developer</div><div><a \
href="http://www.linkedin.com/in/davidwsmiley" \
target="_blank">http://www.linkedin.com/in/davidwsmiley</a></div></div></div></div><br></div></div></div><br><div \
class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Nov 30, 2020 at 3:29 AM \
Adrien Grand <<a href="mailto:jpountz@gmail.com" \
target="_blank">jpountz@gmail.com</a>> wrote:<br></div><blockquote \
class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div \
dir="ltr"><div>I have a preference for maintaining a separate CHANGES file because it \
allows us to keep JIRA focused for a committer/contributor audience while the CHANGES \
file can describe changes that matter for users. Elasticsearch uses a similar \
mechanism for release notes to what you are proposing, using GitHub instead of JIRA. \
It works well, but in my opinion the Lucene/Solr process produces better curated \
release notes.</div><div></div></div><br><div class="gmail_quote"><div dir="ltr" \
class="gmail_attr">On Mon, Nov 30, 2020 at 12:25 AM David Smiley <<a \
href="mailto:dsmiley@apache.org" target="_blank">dsmiley@apache.org</a>> \
wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div \
dir="ltr">Well the commit history remains there as well and was converted from SVN \
and may eventually be converted to something else. My point is that it has been \
retained. On release boundaries, we could not only distribute Changes.html (a JIRA \
export) in the assembly (tar.gz) but we could also commit it to source control on \
each release branch, and thus will transfer along with source control into the \
future, which is way more convenient than digging up an old binary.<div><br \
clear="all"><div><div dir="ltr"><div dir="ltr">~ David Smiley<div>Apache Lucene/Solr \
Search Developer</div><div><a href="http://www.linkedin.com/in/davidwsmiley" \
target="_blank">http://www.linkedin.com/in/davidwsmiley</a></div></div></div></div><br></div></div><br><div \
class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Nov 29, 2020 at 5:55 AM \
Dawid Weiss <<a href="mailto:dawid.weiss@gmail.com" \
target="_blank">dawid.weiss@gmail.com</a>> wrote:<br></div><blockquote \
class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">Changes \
in the repository stay there forever (think<br> cvs/svn/git/whatever comes next...). \
External tools change all the<br> time. This is the benefit I see.<br>
<br>
Dawid<br>
<br>
On Sun, Nov 29, 2020 at 6:32 AM David Smiley <<a href="mailto:dsmiley@apache.org" \
target="_blank">dsmiley@apache.org</a>> wrote:<br> ><br>
> After recently proposing per-module CHANGES.md... I think I'd actually \
rather not have any CHANGES file at all to maintain. I'd rather go to JIRA with \
a bit better hygiene for metadata like components==contrib/module, and have some \
convenient links sprinkled about so that it's a convenient click away from each \
module. This proposal may not be as compelling for Lucene which has no \
solr-upgrade-notes.adoc file.<br> ><br>
> Maintaining this CHANGES file (or files) is a pain. Formatting it just-so \
& conversion to HTML & other scripts manipulating it in dev-tools (e.g. add \
version), and branch syncing. It's commonly a source of merge conflicts more \
than any other file. It's an annoying step with GitHub PRs in particular. Why \
do we bother? Instead, on releases, provide a JIRA link to display all fixed issues \
grouped by issue type. We could export it to a file for direct inclusion in the \
distribution. JIRA even has a feature for this -- here's a direct link for 8.7: \
<a href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12310230&version=12348463" \
rel="noreferrer" target="_blank">https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12310230&version=12348463</a> \
Notice the HTML version at the bottom. It could be dumped into the release \
binaries.<br> > Issue summaries tend to be much shorter than CHANGES.txt bullets \
but I think that's okay because it's not the only information available for \
those who want to know more. Remember there is also all the other metadata in JIRA \
a user can examine, there are commit messages, sometimes PRs, and there's \
solr-upgrade-notes.adoc which ought to be the starting point for someone interested \
in a release.<br> ><br>
> It's been argued that contributors should get attribution here but we could \
maintain a separate contributors file to acknowledge people by name for inclusion \
with the Solr distribution -- one that has a link to JIRA and GitHub even.<br> \
><br> > ~ David Smiley<br>
> Apache Lucene/Solr Search Developer<br>
> <a href="http://www.linkedin.com/in/davidwsmiley" rel="noreferrer" \
target="_blank">http://www.linkedin.com/in/davidwsmiley</a><br> <br>
---------------------------------------------------------------------<br>
To unsubscribe, e-mail: <a href="mailto:dev-unsubscribe@lucene.apache.org" \
target="_blank">dev-unsubscribe@lucene.apache.org</a><br> For additional commands, \
e-mail: <a href="mailto:dev-help@lucene.apache.org" \
target="_blank">dev-help@lucene.apache.org</a><br> <br>
</blockquote></div>
</blockquote></div><br clear="all"><div><br></div>-- <br><div dir="ltr">Adrien</div>
</blockquote></div>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic