Mailing List Archive

Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...
I was about to merge a PR pertaining to Solr's new Docker module when it
occurred to me that I ought to add a CHANGES.txt entry. But, for Solr
users (which includes me and everyone reading this), it's annoying to have
to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade
notes, which is a distinct way of running Solr. I think the same could be
said for our contribs, and perhaps even SolrJ, which is another distinct
consumable. The idea of separated CHANGES.txt aligns well with contribs
being further isolated (see both the discussion on separate git repos for
them, and also the discussion of getting rid of "dist" (each contrib's jar
goes in its own folder; keeps to itself)).

Solr's root /CHANGES.txt could at the very top reference the other
CHANGES.txt files.

WDYT?

~ David Smiley
Apache Lucene/Solr Search Developer
http://www.linkedin.com/in/davidwsmiley
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
I think whatever we don't ship in the main tarball today should stay
separate. Going forward, when we stop shoving the extra modules (contribs)
into the main distro, we can separate out their changelogs. However, I feel
SolrJ changes should stay with Solr changes since it is also used heavily
in the server side.

On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org> wrote:

> I was about to merge a PR pertaining to Solr's new Docker module when it
> occurred to me that I ought to add a CHANGES.txt entry. But, for Solr
> users (which includes me and everyone reading this), it's annoying to have
> to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade
> notes, which is a distinct way of running Solr. I think the same could be
> said for our contribs, and perhaps even SolrJ, which is another distinct
> consumable. The idea of separated CHANGES.txt aligns well with contribs
> being further isolated (see both the discussion on separate git repos for
> them, and also the discussion of getting rid of "dist" (each contrib's jar
> goes in its own folder; keeps to itself)).
>
> Solr's root /CHANGES.txt could at the very top reference the other
> CHANGES.txt files.
>
> WDYT?
>
> ~ David Smiley
> Apache Lucene/Solr Search Developer
> http://www.linkedin.com/in/davidwsmiley
>
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
What of Docker changes? And beyond direct changes to Dockerfile + scripts,
it could feature particular notable changes to the server that are
particularly noteworthy... like hypothetical improvements to solr home /
core root dir etc. configuration.

Even if Contribs/Modules are not separated out of the repo *yet* (even if
they hypothetically never leave), I think it's desirable to separate their
CHANGES.txt in master now.

RE SolrJ -- I know it's used heavily in the server side; this one is more
debatable than the others and I don't have a strong opinion. Some items
that have a more sweeping impact (e.g. HTTP2) would be listed in both but
the difference is that the SolrJ side would have a more user-facing
purpose, mentioning SolrClient subclasses that are pertinent to draw
attention to compatibility or new classes users should know about. This
kind of stuff is maybe too detailed to bother putting in
solr-upgrade-notes.adoc but would not be to SolrJ's dedicated CHANGES.txt.
On server CHANGES.txt, we tend to be vague. If SolrJ is changed for
something that has more to do with server-side (e.g. SOLR-14691 "Metrics
Reporting Should Avoid Creating Objects" which changed some utils in
SolrJ), then it ought not to be listed in SolrJ's proposed CHANGES.txt.
Admittedly there may be more cumulative CHANGES.txt maintenance between the
two.

~ David Smiley
Apache Lucene/Solr Search Developer
http://www.linkedin.com/in/davidwsmiley


On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <
ichattopadhyaya@gmail.com> wrote:

> I think whatever we don't ship in the main tarball today should stay
> separate. Going forward, when we stop shoving the extra modules (contribs)
> into the main distro, we can separate out their changelogs. However, I feel
> SolrJ changes should stay with Solr changes since it is also used heavily
> in the server side.
>
> On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org> wrote:
>
>> I was about to merge a PR pertaining to Solr's new Docker module when it
>> occurred to me that I ought to add a CHANGES.txt entry. But, for Solr
>> users (which includes me and everyone reading this), it's annoying to have
>> to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade
>> notes, which is a distinct way of running Solr. I think the same could be
>> said for our contribs, and perhaps even SolrJ, which is another distinct
>> consumable. The idea of separated CHANGES.txt aligns well with contribs
>> being further isolated (see both the discussion on separate git repos for
>> them, and also the discussion of getting rid of "dist" (each contrib's jar
>> goes in its own folder; keeps to itself)).
>>
>> Solr's root /CHANGES.txt could at the very top reference the other
>> CHANGES.txt files.
>>
>> WDYT?
>>
>> ~ David Smiley
>> Apache Lucene/Solr Search Developer
>> http://www.linkedin.com/in/davidwsmiley
>>
>
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
+1

I think that having separate CHANGES.txt files for the different parts of
Solr would be great. If you are looking for certain changes you would
generally know which module to go to.

Some items that have a more sweeping impact would be listed in both


I am ambivalent on having a separate CHANGES.txt for SolrJ, as long as
major changes are included in the main CHANGES.txt. In general it's easy to
add an entry to every applicable CHANGES.txt, no matter which module the
change was made in.

- Houston

On Sat, Nov 21, 2020 at 1:34 AM David Smiley <dsmiley@apache.org> wrote:

> What of Docker changes? And beyond direct changes to Dockerfile +
> scripts, it could feature particular notable changes to the server that are
> particularly noteworthy... like hypothetical improvements to solr home /
> core root dir etc. configuration.
>
> Even if Contribs/Modules are not separated out of the repo *yet* (even if
> they hypothetically never leave), I think it's desirable to separate their
> CHANGES.txt in master now.
>
> RE SolrJ -- I know it's used heavily in the server side; this one is more
> debatable than the others and I don't have a strong opinion. Some items
> that have a more sweeping impact (e.g. HTTP2) would be listed in both but
> the difference is that the SolrJ side would have a more user-facing
> purpose, mentioning SolrClient subclasses that are pertinent to draw
> attention to compatibility or new classes users should know about. This
> kind of stuff is maybe too detailed to bother putting in
> solr-upgrade-notes.adoc but would not be to SolrJ's dedicated CHANGES.txt.
> On server CHANGES.txt, we tend to be vague. If SolrJ is changed for
> something that has more to do with server-side (e.g. SOLR-14691 "Metrics
> Reporting Should Avoid Creating Objects" which changed some utils in
> SolrJ), then it ought not to be listed in SolrJ's proposed CHANGES.txt.
> Admittedly there may be more cumulative CHANGES.txt maintenance between the
> two.
>
> ~ David Smiley
> Apache Lucene/Solr Search Developer
> http://www.linkedin.com/in/davidwsmiley
>
>
> On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <
> ichattopadhyaya@gmail.com> wrote:
>
>> I think whatever we don't ship in the main tarball today should stay
>> separate. Going forward, when we stop shoving the extra modules (contribs)
>> into the main distro, we can separate out their changelogs. However, I feel
>> SolrJ changes should stay with Solr changes since it is also used heavily
>> in the server side.
>>
>> On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org> wrote:
>>
>>> I was about to merge a PR pertaining to Solr's new Docker module when it
>>> occurred to me that I ought to add a CHANGES.txt entry. But, for Solr
>>> users (which includes me and everyone reading this), it's annoying to have
>>> to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade
>>> notes, which is a distinct way of running Solr. I think the same could be
>>> said for our contribs, and perhaps even SolrJ, which is another distinct
>>> consumable. The idea of separated CHANGES.txt aligns well with contribs
>>> being further isolated (see both the discussion on separate git repos for
>>> them, and also the discussion of getting rid of "dist" (each contrib's jar
>>> goes in its own folder; keeps to itself)).
>>>
>>> Solr's root /CHANGES.txt could at the very top reference the other
>>> CHANGES.txt files.
>>>
>>> WDYT?
>>>
>>> ~ David Smiley
>>> Apache Lucene/Solr Search Developer
>>> http://www.linkedin.com/in/davidwsmiley
>>>
>>
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
I pushed a commit to a PR for the prometheus exporter that includes a
CHANGES.md
https://github.com/apache/lucene-solr/pull/1972/commits/bec84ce2a1d60480ce0c54b78e83a70f83e7b058
and likewise for a commit to a PR for the docker module:
https://github.com/apache/lucene-solr/pull/2083/commits/540f8117153d12bd13441326035820f97084878a

* I chose the Markdown format. This is an opportune time to switch. This
meant changing "==== 9.0 ====" to "9.0" then "======" beneath it, but
otherwise, no changes!
* I chose to start this for 9.0. Any changes prior to 9.0 I think should
continue to do things as we have been doing things historically.
* I considered updating dev-tools/scripts/addVersion.py but ultimately
elected not to. I think the rate of changes in each module will be low
enough that it's not a big deal to maintain it manually. Plus, I confess
I'm less motivated to touch Python ;-) but I'd be more than happy to see
someone automate this.

If this is agreeable, Solr's master CHANGES.txt ought to have references to
CHANGES.md for contribs & Docker.

~ David Smiley
Apache Lucene/Solr Search Developer
http://www.linkedin.com/in/davidwsmiley


On Mon, Nov 23, 2020 at 11:56 AM Houston Putman <houstonputman@gmail.com>
wrote:

> +1
>
> I think that having separate CHANGES.txt files for the different parts of
> Solr would be great. If you are looking for certain changes you would
> generally know which module to go to.
>
> Some items that have a more sweeping impact would be listed in both
>
>
> I am ambivalent on having a separate CHANGES.txt for SolrJ, as long as
> major changes are included in the main CHANGES.txt. In general it's easy to
> add an entry to every applicable CHANGES.txt, no matter which module the
> change was made in.
>
> - Houston
>
> On Sat, Nov 21, 2020 at 1:34 AM David Smiley <dsmiley@apache.org> wrote:
>
>> What of Docker changes? And beyond direct changes to Dockerfile +
>> scripts, it could feature particular notable changes to the server that are
>> particularly noteworthy... like hypothetical improvements to solr home /
>> core root dir etc. configuration.
>>
>> Even if Contribs/Modules are not separated out of the repo *yet* (even if
>> they hypothetically never leave), I think it's desirable to separate their
>> CHANGES.txt in master now.
>>
>> RE SolrJ -- I know it's used heavily in the server side; this one is more
>> debatable than the others and I don't have a strong opinion. Some items
>> that have a more sweeping impact (e.g. HTTP2) would be listed in both but
>> the difference is that the SolrJ side would have a more user-facing
>> purpose, mentioning SolrClient subclasses that are pertinent to draw
>> attention to compatibility or new classes users should know about. This
>> kind of stuff is maybe too detailed to bother putting in
>> solr-upgrade-notes.adoc but would not be to SolrJ's dedicated CHANGES.txt.
>> On server CHANGES.txt, we tend to be vague. If SolrJ is changed for
>> something that has more to do with server-side (e.g. SOLR-14691 "Metrics
>> Reporting Should Avoid Creating Objects" which changed some utils in
>> SolrJ), then it ought not to be listed in SolrJ's proposed CHANGES.txt.
>> Admittedly there may be more cumulative CHANGES.txt maintenance between the
>> two.
>>
>> ~ David Smiley
>> Apache Lucene/Solr Search Developer
>> http://www.linkedin.com/in/davidwsmiley
>>
>>
>> On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <
>> ichattopadhyaya@gmail.com> wrote:
>>
>>> I think whatever we don't ship in the main tarball today should stay
>>> separate. Going forward, when we stop shoving the extra modules (contribs)
>>> into the main distro, we can separate out their changelogs. However, I feel
>>> SolrJ changes should stay with Solr changes since it is also used heavily
>>> in the server side.
>>>
>>> On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org> wrote:
>>>
>>>> I was about to merge a PR pertaining to Solr's new Docker module when
>>>> it occurred to me that I ought to add a CHANGES.txt entry. But, for Solr
>>>> users (which includes me and everyone reading this), it's annoying to have
>>>> to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade
>>>> notes, which is a distinct way of running Solr. I think the same could be
>>>> said for our contribs, and perhaps even SolrJ, which is another distinct
>>>> consumable. The idea of separated CHANGES.txt aligns well with contribs
>>>> being further isolated (see both the discussion on separate git repos for
>>>> them, and also the discussion of getting rid of "dist" (each contrib's jar
>>>> goes in its own folder; keeps to itself)).
>>>>
>>>> Solr's root /CHANGES.txt could at the very top reference the other
>>>> CHANGES.txt files.
>>>>
>>>> WDYT?
>>>>
>>>> ~ David Smiley
>>>> Apache Lucene/Solr Search Developer
>>>> http://www.linkedin.com/in/davidwsmiley
>>>>
>>>
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
Should we switch to a structured format, instead of current format that
tools struggle to convert.

Something that one could push into Solr would have been nice...

Regards,
Alex

On Mon., Nov. 23, 2020, 4:47 p.m. David Smiley, <dsmiley@apache.org> wrote:

> I pushed a commit to a PR for the prometheus exporter that includes a
> CHANGES.md
>
> https://github.com/apache/lucene-solr/pull/1972/commits/bec84ce2a1d60480ce0c54b78e83a70f83e7b058
> and likewise for a commit to a PR for the docker module:
>
> https://github.com/apache/lucene-solr/pull/2083/commits/540f8117153d12bd13441326035820f97084878a
>
> * I chose the Markdown format. This is an opportune time to switch. This
> meant changing "==== 9.0 ====" to "9.0" then "======" beneath it, but
> otherwise, no changes!
> * I chose to start this for 9.0. Any changes prior to 9.0 I think should
> continue to do things as we have been doing things historically.
> * I considered updating dev-tools/scripts/addVersion.py but ultimately
> elected not to. I think the rate of changes in each module will be low
> enough that it's not a big deal to maintain it manually. Plus, I confess
> I'm less motivated to touch Python ;-) but I'd be more than happy to see
> someone automate this.
>
> If this is agreeable, Solr's master CHANGES.txt ought to have references
> to CHANGES.md for contribs & Docker.
>
> ~ David Smiley
> Apache Lucene/Solr Search Developer
> http://www.linkedin.com/in/davidwsmiley
>
>
> On Mon, Nov 23, 2020 at 11:56 AM Houston Putman <houstonputman@gmail.com>
> wrote:
>
>> +1
>>
>> I think that having separate CHANGES.txt files for the different parts of
>> Solr would be great. If you are looking for certain changes you would
>> generally know which module to go to.
>>
>> Some items that have a more sweeping impact would be listed in both
>>
>>
>> I am ambivalent on having a separate CHANGES.txt for SolrJ, as long as
>> major changes are included in the main CHANGES.txt. In general it's easy to
>> add an entry to every applicable CHANGES.txt, no matter which module the
>> change was made in.
>>
>> - Houston
>>
>> On Sat, Nov 21, 2020 at 1:34 AM David Smiley <dsmiley@apache.org> wrote:
>>
>>> What of Docker changes? And beyond direct changes to Dockerfile +
>>> scripts, it could feature particular notable changes to the server that are
>>> particularly noteworthy... like hypothetical improvements to solr home /
>>> core root dir etc. configuration.
>>>
>>> Even if Contribs/Modules are not separated out of the repo *yet* (even
>>> if they hypothetically never leave), I think it's desirable to separate
>>> their CHANGES.txt in master now.
>>>
>>> RE SolrJ -- I know it's used heavily in the server side; this one is
>>> more debatable than the others and I don't have a strong opinion. Some
>>> items that have a more sweeping impact (e.g. HTTP2) would be listed in both
>>> but the difference is that the SolrJ side would have a more user-facing
>>> purpose, mentioning SolrClient subclasses that are pertinent to draw
>>> attention to compatibility or new classes users should know about. This
>>> kind of stuff is maybe too detailed to bother putting in
>>> solr-upgrade-notes.adoc but would not be to SolrJ's dedicated CHANGES.txt.
>>> On server CHANGES.txt, we tend to be vague. If SolrJ is changed for
>>> something that has more to do with server-side (e.g. SOLR-14691 "Metrics
>>> Reporting Should Avoid Creating Objects" which changed some utils in
>>> SolrJ), then it ought not to be listed in SolrJ's proposed CHANGES.txt.
>>> Admittedly there may be more cumulative CHANGES.txt maintenance between the
>>> two.
>>>
>>> ~ David Smiley
>>> Apache Lucene/Solr Search Developer
>>> http://www.linkedin.com/in/davidwsmiley
>>>
>>>
>>> On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <
>>> ichattopadhyaya@gmail.com> wrote:
>>>
>>>> I think whatever we don't ship in the main tarball today should stay
>>>> separate. Going forward, when we stop shoving the extra modules (contribs)
>>>> into the main distro, we can separate out their changelogs. However, I feel
>>>> SolrJ changes should stay with Solr changes since it is also used heavily
>>>> in the server side.
>>>>
>>>> On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org> wrote:
>>>>
>>>>> I was about to merge a PR pertaining to Solr's new Docker module when
>>>>> it occurred to me that I ought to add a CHANGES.txt entry. But, for Solr
>>>>> users (which includes me and everyone reading this), it's annoying to have
>>>>> to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade
>>>>> notes, which is a distinct way of running Solr. I think the same could be
>>>>> said for our contribs, and perhaps even SolrJ, which is another distinct
>>>>> consumable. The idea of separated CHANGES.txt aligns well with contribs
>>>>> being further isolated (see both the discussion on separate git repos for
>>>>> them, and also the discussion of getting rid of "dist" (each contrib's jar
>>>>> goes in its own folder; keeps to itself)).
>>>>>
>>>>> Solr's root /CHANGES.txt could at the very top reference the other
>>>>> CHANGES.txt files.
>>>>>
>>>>> WDYT?
>>>>>
>>>>> ~ David Smiley
>>>>> Apache Lucene/Solr Search Developer
>>>>> http://www.linkedin.com/in/davidwsmiley
>>>>>
>>>>
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
And - afterthought - if there is an easily parsable format, the parser
could even run at the commit time on GitHub to make sure that issue
numbers are correct, names are included and formatting is not broken.

Regards,
Alex.

On Mon, 23 Nov 2020 at 19:38, Alexandre Rafalovitch <arafalov@gmail.com> wrote:
>
> Should we switch to a structured format, instead of current format that tools struggle to convert.
>
> Something that one could push into Solr would have been nice...
>
> Regards,
> Alex
>
> On Mon., Nov. 23, 2020, 4:47 p.m. David Smiley, <dsmiley@apache.org> wrote:
>>
>> I pushed a commit to a PR for the prometheus exporter that includes a CHANGES.md
>> https://github.com/apache/lucene-solr/pull/1972/commits/bec84ce2a1d60480ce0c54b78e83a70f83e7b058
>> and likewise for a commit to a PR for the docker module:
>> https://github.com/apache/lucene-solr/pull/2083/commits/540f8117153d12bd13441326035820f97084878a
>>
>> * I chose the Markdown format. This is an opportune time to switch. This meant changing "==== 9.0 ====" to "9.0" then "======" beneath it, but otherwise, no changes!
>> * I chose to start this for 9.0. Any changes prior to 9.0 I think should continue to do things as we have been doing things historically.
>> * I considered updating dev-tools/scripts/addVersion.py but ultimately elected not to. I think the rate of changes in each module will be low enough that it's not a big deal to maintain it manually. Plus, I confess I'm less motivated to touch Python ;-) but I'd be more than happy to see someone automate this.
>>
>> If this is agreeable, Solr's master CHANGES.txt ought to have references to CHANGES.md for contribs & Docker.
>>
>> ~ David Smiley
>> Apache Lucene/Solr Search Developer
>> http://www.linkedin.com/in/davidwsmiley
>>
>>
>> On Mon, Nov 23, 2020 at 11:56 AM Houston Putman <houstonputman@gmail.com> wrote:
>>>
>>> +1
>>>
>>> I think that having separate CHANGES.txt files for the different parts of Solr would be great. If you are looking for certain changes you would generally know which module to go to.
>>>
>>>> Some items that have a more sweeping impact would be listed in both
>>>
>>>
>>> I am ambivalent on having a separate CHANGES.txt for SolrJ, as long as major changes are included in the main CHANGES.txt. In general it's easy to add an entry to every applicable CHANGES.txt, no matter which module the change was made in.
>>>
>>> - Houston
>>>
>>> On Sat, Nov 21, 2020 at 1:34 AM David Smiley <dsmiley@apache.org> wrote:
>>>>
>>>> What of Docker changes? And beyond direct changes to Dockerfile + scripts, it could feature particular notable changes to the server that are particularly noteworthy... like hypothetical improvements to solr home / core root dir etc. configuration.
>>>>
>>>> Even if Contribs/Modules are not separated out of the repo *yet* (even if they hypothetically never leave), I think it's desirable to separate their CHANGES.txt in master now.
>>>>
>>>> RE SolrJ -- I know it's used heavily in the server side; this one is more debatable than the others and I don't have a strong opinion. Some items that have a more sweeping impact (e.g. HTTP2) would be listed in both but the difference is that the SolrJ side would have a more user-facing purpose, mentioning SolrClient subclasses that are pertinent to draw attention to compatibility or new classes users should know about. This kind of stuff is maybe too detailed to bother putting in solr-upgrade-notes.adoc but would not be to SolrJ's dedicated CHANGES.txt. On server CHANGES.txt, we tend to be vague. If SolrJ is changed for something that has more to do with server-side (e.g. SOLR-14691 "Metrics Reporting Should Avoid Creating Objects" which changed some utils in SolrJ), then it ought not to be listed in SolrJ's proposed CHANGES.txt. Admittedly there may be more cumulative CHANGES.txt maintenance between the two.
>>>>
>>>> ~ David Smiley
>>>> Apache Lucene/Solr Search Developer
>>>> http://www.linkedin.com/in/davidwsmiley
>>>>
>>>>
>>>> On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <ichattopadhyaya@gmail.com> wrote:
>>>>>
>>>>> I think whatever we don't ship in the main tarball today should stay separate. Going forward, when we stop shoving the extra modules (contribs) into the main distro, we can separate out their changelogs. However, I feel SolrJ changes should stay with Solr changes since it is also used heavily in the server side.
>>>>>
>>>>> On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org> wrote:
>>>>>>
>>>>>> I was about to merge a PR pertaining to Solr's new Docker module when it occurred to me that I ought to add a CHANGES.txt entry. But, for Solr users (which includes me and everyone reading this), it's annoying to have to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade notes, which is a distinct way of running Solr. I think the same could be said for our contribs, and perhaps even SolrJ, which is another distinct consumable. The idea of separated CHANGES.txt aligns well with contribs being further isolated (see both the discussion on separate git repos for them, and also the discussion of getting rid of "dist" (each contrib's jar goes in its own folder; keeps to itself)).
>>>>>>
>>>>>> Solr's root /CHANGES.txt could at the very top reference the other CHANGES.txt files.
>>>>>>
>>>>>> WDYT?
>>>>>>
>>>>>> ~ 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
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
I'd rather not scope-creep my proposal here further. Granted I ventured
into TXT -> Markdown.

~ David Smiley
Apache Lucene/Solr Search Developer
http://www.linkedin.com/in/davidwsmiley


On Tue, Nov 24, 2020 at 9:37 AM Alexandre Rafalovitch <arafalov@gmail.com>
wrote:

> And - afterthought - if there is an easily parsable format, the parser
> could even run at the commit time on GitHub to make sure that issue
> numbers are correct, names are included and formatting is not broken.
>
> Regards,
> Alex.
>
> On Mon, 23 Nov 2020 at 19:38, Alexandre Rafalovitch <arafalov@gmail.com>
> wrote:
> >
> > Should we switch to a structured format, instead of current format that
> tools struggle to convert.
> >
> > Something that one could push into Solr would have been nice...
> >
> > Regards,
> > Alex
> >
> > On Mon., Nov. 23, 2020, 4:47 p.m. David Smiley, <dsmiley@apache.org>
> wrote:
> >>
> >> I pushed a commit to a PR for the prometheus exporter that includes a
> CHANGES.md
> >>
> https://github.com/apache/lucene-solr/pull/1972/commits/bec84ce2a1d60480ce0c54b78e83a70f83e7b058
> >> and likewise for a commit to a PR for the docker module:
> >>
> https://github.com/apache/lucene-solr/pull/2083/commits/540f8117153d12bd13441326035820f97084878a
> >>
> >> * I chose the Markdown format. This is an opportune time to switch.
> This meant changing "==== 9.0 ====" to "9.0" then "======" beneath it, but
> otherwise, no changes!
> >> * I chose to start this for 9.0. Any changes prior to 9.0 I think
> should continue to do things as we have been doing things historically.
> >> * I considered updating dev-tools/scripts/addVersion.py but ultimately
> elected not to. I think the rate of changes in each module will be low
> enough that it's not a big deal to maintain it manually. Plus, I confess
> I'm less motivated to touch Python ;-) but I'd be more than happy to see
> someone automate this.
> >>
> >> If this is agreeable, Solr's master CHANGES.txt ought to have
> references to CHANGES.md for contribs & Docker.
> >>
> >> ~ David Smiley
> >> Apache Lucene/Solr Search Developer
> >> http://www.linkedin.com/in/davidwsmiley
> >>
> >>
> >> On Mon, Nov 23, 2020 at 11:56 AM Houston Putman <
> houstonputman@gmail.com> wrote:
> >>>
> >>> +1
> >>>
> >>> I think that having separate CHANGES.txt files for the different parts
> of Solr would be great. If you are looking for certain changes you would
> generally know which module to go to.
> >>>
> >>>> Some items that have a more sweeping impact would be listed in both
> >>>
> >>>
> >>> I am ambivalent on having a separate CHANGES.txt for SolrJ, as long as
> major changes are included in the main CHANGES.txt. In general it's easy to
> add an entry to every applicable CHANGES.txt, no matter which module the
> change was made in.
> >>>
> >>> - Houston
> >>>
> >>> On Sat, Nov 21, 2020 at 1:34 AM David Smiley <dsmiley@apache.org>
> wrote:
> >>>>
> >>>> What of Docker changes? And beyond direct changes to Dockerfile +
> scripts, it could feature particular notable changes to the server that are
> particularly noteworthy... like hypothetical improvements to solr home /
> core root dir etc. configuration.
> >>>>
> >>>> Even if Contribs/Modules are not separated out of the repo *yet*
> (even if they hypothetically never leave), I think it's desirable to
> separate their CHANGES.txt in master now.
> >>>>
> >>>> RE SolrJ -- I know it's used heavily in the server side; this one is
> more debatable than the others and I don't have a strong opinion. Some
> items that have a more sweeping impact (e.g. HTTP2) would be listed in both
> but the difference is that the SolrJ side would have a more user-facing
> purpose, mentioning SolrClient subclasses that are pertinent to draw
> attention to compatibility or new classes users should know about. This
> kind of stuff is maybe too detailed to bother putting in
> solr-upgrade-notes.adoc but would not be to SolrJ's dedicated CHANGES.txt.
> On server CHANGES.txt, we tend to be vague. If SolrJ is changed for
> something that has more to do with server-side (e.g. SOLR-14691 "Metrics
> Reporting Should Avoid Creating Objects" which changed some utils in
> SolrJ), then it ought not to be listed in SolrJ's proposed CHANGES.txt.
> Admittedly there may be more cumulative CHANGES.txt maintenance between the
> two.
> >>>>
> >>>> ~ David Smiley
> >>>> Apache Lucene/Solr Search Developer
> >>>> http://www.linkedin.com/in/davidwsmiley
> >>>>
> >>>>
> >>>> On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <
> ichattopadhyaya@gmail.com> wrote:
> >>>>>
> >>>>> I think whatever we don't ship in the main tarball today should stay
> separate. Going forward, when we stop shoving the extra modules (contribs)
> into the main distro, we can separate out their changelogs. However, I feel
> SolrJ changes should stay with Solr changes since it is also used heavily
> in the server side.
> >>>>>
> >>>>> On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org>
> wrote:
> >>>>>>
> >>>>>> I was about to merge a PR pertaining to Solr's new Docker module
> when it occurred to me that I ought to add a CHANGES.txt entry. But, for
> Solr users (which includes me and everyone reading this), it's annoying to
> have to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade
> notes, which is a distinct way of running Solr. I think the same could be
> said for our contribs, and perhaps even SolrJ, which is another distinct
> consumable. The idea of separated CHANGES.txt aligns well with contribs
> being further isolated (see both the discussion on separate git repos for
> them, and also the discussion of getting rid of "dist" (each contrib's jar
> goes in its own folder; keeps to itself)).
> >>>>>>
> >>>>>> Solr's root /CHANGES.txt could at the very top reference the other
> CHANGES.txt files.
> >>>>>>
> >>>>>> WDYT?
> >>>>>>
> >>>>>> ~ 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
>
>
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
Absolutely.

What I was trying to say is that when it comes to implementation,
there may be a choice of strategies to do so within the same scope. A
strategy that aligns better with something that - with more work -
eventually becomes true structured data may have more long-term value
than a strategy that does not.

Hope that makes sense.

Regards,
Alex.

On Tue, 24 Nov 2020 at 12:13, David Smiley <dsmiley@apache.org> wrote:
>
> I'd rather not scope-creep my proposal here further. Granted I ventured into TXT -> Markdown.
>
> ~ David Smiley
> Apache Lucene/Solr Search Developer
> http://www.linkedin.com/in/davidwsmiley
>
>
> On Tue, Nov 24, 2020 at 9:37 AM Alexandre Rafalovitch <arafalov@gmail.com> wrote:
>>
>> And - afterthought - if there is an easily parsable format, the parser
>> could even run at the commit time on GitHub to make sure that issue
>> numbers are correct, names are included and formatting is not broken.
>>
>> Regards,
>> Alex.
>>
>> On Mon, 23 Nov 2020 at 19:38, Alexandre Rafalovitch <arafalov@gmail.com> wrote:
>> >
>> > Should we switch to a structured format, instead of current format that tools struggle to convert.
>> >
>> > Something that one could push into Solr would have been nice...
>> >
>> > Regards,
>> > Alex
>> >
>> > On Mon., Nov. 23, 2020, 4:47 p.m. David Smiley, <dsmiley@apache.org> wrote:
>> >>
>> >> I pushed a commit to a PR for the prometheus exporter that includes a CHANGES.md
>> >> https://github.com/apache/lucene-solr/pull/1972/commits/bec84ce2a1d60480ce0c54b78e83a70f83e7b058
>> >> and likewise for a commit to a PR for the docker module:
>> >> https://github.com/apache/lucene-solr/pull/2083/commits/540f8117153d12bd13441326035820f97084878a
>> >>
>> >> * I chose the Markdown format. This is an opportune time to switch. This meant changing "==== 9.0 ====" to "9.0" then "======" beneath it, but otherwise, no changes!
>> >> * I chose to start this for 9.0. Any changes prior to 9.0 I think should continue to do things as we have been doing things historically.
>> >> * I considered updating dev-tools/scripts/addVersion.py but ultimately elected not to. I think the rate of changes in each module will be low enough that it's not a big deal to maintain it manually. Plus, I confess I'm less motivated to touch Python ;-) but I'd be more than happy to see someone automate this.
>> >>
>> >> If this is agreeable, Solr's master CHANGES.txt ought to have references to CHANGES.md for contribs & Docker.
>> >>
>> >> ~ David Smiley
>> >> Apache Lucene/Solr Search Developer
>> >> http://www.linkedin.com/in/davidwsmiley
>> >>
>> >>
>> >> On Mon, Nov 23, 2020 at 11:56 AM Houston Putman <houstonputman@gmail.com> wrote:
>> >>>
>> >>> +1
>> >>>
>> >>> I think that having separate CHANGES.txt files for the different parts of Solr would be great. If you are looking for certain changes you would generally know which module to go to.
>> >>>
>> >>>> Some items that have a more sweeping impact would be listed in both
>> >>>
>> >>>
>> >>> I am ambivalent on having a separate CHANGES.txt for SolrJ, as long as major changes are included in the main CHANGES.txt. In general it's easy to add an entry to every applicable CHANGES.txt, no matter which module the change was made in.
>> >>>
>> >>> - Houston
>> >>>
>> >>> On Sat, Nov 21, 2020 at 1:34 AM David Smiley <dsmiley@apache.org> wrote:
>> >>>>
>> >>>> What of Docker changes? And beyond direct changes to Dockerfile + scripts, it could feature particular notable changes to the server that are particularly noteworthy... like hypothetical improvements to solr home / core root dir etc. configuration.
>> >>>>
>> >>>> Even if Contribs/Modules are not separated out of the repo *yet* (even if they hypothetically never leave), I think it's desirable to separate their CHANGES.txt in master now.
>> >>>>
>> >>>> RE SolrJ -- I know it's used heavily in the server side; this one is more debatable than the others and I don't have a strong opinion. Some items that have a more sweeping impact (e.g. HTTP2) would be listed in both but the difference is that the SolrJ side would have a more user-facing purpose, mentioning SolrClient subclasses that are pertinent to draw attention to compatibility or new classes users should know about. This kind of stuff is maybe too detailed to bother putting in solr-upgrade-notes.adoc but would not be to SolrJ's dedicated CHANGES.txt. On server CHANGES.txt, we tend to be vague. If SolrJ is changed for something that has more to do with server-side (e.g. SOLR-14691 "Metrics Reporting Should Avoid Creating Objects" which changed some utils in SolrJ), then it ought not to be listed in SolrJ's proposed CHANGES.txt. Admittedly there may be more cumulative CHANGES.txt maintenance between the two.
>> >>>>
>> >>>> ~ David Smiley
>> >>>> Apache Lucene/Solr Search Developer
>> >>>> http://www.linkedin.com/in/davidwsmiley
>> >>>>
>> >>>>
>> >>>> On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <ichattopadhyaya@gmail.com> wrote:
>> >>>>>
>> >>>>> I think whatever we don't ship in the main tarball today should stay separate. Going forward, when we stop shoving the extra modules (contribs) into the main distro, we can separate out their changelogs. However, I feel SolrJ changes should stay with Solr changes since it is also used heavily in the server side.
>> >>>>>
>> >>>>> On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org> wrote:
>> >>>>>>
>> >>>>>> I was about to merge a PR pertaining to Solr's new Docker module when it occurred to me that I ought to add a CHANGES.txt entry. But, for Solr users (which includes me and everyone reading this), it's annoying to have to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade notes, which is a distinct way of running Solr. I think the same could be said for our contribs, and perhaps even SolrJ, which is another distinct consumable. The idea of separated CHANGES.txt aligns well with contribs being further isolated (see both the discussion on separate git repos for them, and also the discussion of getting rid of "dist" (each contrib's jar goes in its own folder; keeps to itself)).
>> >>>>>>
>> >>>>>> Solr's root /CHANGES.txt could at the very top reference the other CHANGES.txt files.
>> >>>>>>
>> >>>>>> WDYT?
>> >>>>>>
>> >>>>>> ~ 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
>>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ... [ In reply to ]
For some days now, the prometheus exporter & Docker modules have their own
CHANGES.md on master. I was about to add a CHANGES.md for the rest of the
contribs last week... but... instead ***I'm going to reverse this***; merge
the entries into solr/CHANGES.txt. I still think it's better than a single
CHANGES.txt for Solr, and I'd even more prefer no CHANGES.txt to maintain
at all. But I don't have time/energy to pursue either approach. This
limbo state at present isn't cool, so I'm choosing to back out.

What follows is what I wrote last week prior to jumping on the idea that
I'd rather we not bother with any CHANGES.txt. I'm including it here as a
sort of note to self and others who want to explore this topic more. The
questions therein are _not_ an active prompt to the community at this time.

-------------
I've noticed some build/release infrastructure that either assumes only
Lucene & Solr have a CHANGES.txt, or don't know how to handle Markdown.

* gradlew changesToHtml on the Lucene & Solr "documentation" sub-projects,
which executes a changes2html.pl (a perl script) which parses CHANGES.txt
to produce a Changes.html file. Here's what that looks like:
https://lucene.apache.org/solr/8_7_0/changes/Changes.html
Question: Might it be good enough if this file had a header with links to
each contrib's CHANGES.md as viewed on GitHub, which renders the Markdown
to a browser?:
https://github.com/apache/lucene-solr/blob/master/solr/contrib/prometheus-exporter/CHANGES.md
(the "master" would change to 9.0.0 upon the release). The biggest benefit
of changes2html.pl is that it makes SOLR-XXXX links to JIRA. In the
Markdown files we could link-ify them ourselves as we edit the file --
rather trivial to maintain; in practice we'd copy another link nearby and
edit it to have the right JIRA reference at the tail end of the URL and for
the display part.

* releaseWizard.yaml invokes releasedJirasRegex.py on CHANGES.txt which
produces a regular expression matching LUCENE-XXXX & SOLR-XXXX JIRA
references for the most recent release. It doesn't understand the markdown
based syntax for the release headings in CHANGES.md although a small change
in the heading syntax choice could make that trivial to fix. Any way...
the goal here is for the RM to sync the changes on the release branch over
to master branch. Today, the RM does this for Lucene & Solr. I suppose
additional CHANGES.md per contrib/module implies doing this for each of
those as well. :-( At least contrib/modules change at a slow pace but
still.


On Tue, Nov 24, 2020 at 4:48 PM Alexandre Rafalovitch <arafalov@gmail.com>
wrote:

> Absolutely.
>
> What I was trying to say is that when it comes to implementation,
> there may be a choice of strategies to do so within the same scope. A
> strategy that aligns better with something that - with more work -
> eventually becomes true structured data may have more long-term value
> than a strategy that does not.
>
> Hope that makes sense.
>
> Regards,
> Alex.
>
> On Tue, 24 Nov 2020 at 12:13, David Smiley <dsmiley@apache.org> wrote:
> >
> > I'd rather not scope-creep my proposal here further. Granted I ventured
> into TXT -> Markdown.
> >
> > ~ David Smiley
> > Apache Lucene/Solr Search Developer
> > http://www.linkedin.com/in/davidwsmiley
> >
> >
> > On Tue, Nov 24, 2020 at 9:37 AM Alexandre Rafalovitch <
> arafalov@gmail.com> wrote:
> >>
> >> And - afterthought - if there is an easily parsable format, the parser
> >> could even run at the commit time on GitHub to make sure that issue
> >> numbers are correct, names are included and formatting is not broken.
> >>
> >> Regards,
> >> Alex.
> >>
> >> On Mon, 23 Nov 2020 at 19:38, Alexandre Rafalovitch <arafalov@gmail.com>
> wrote:
> >> >
> >> > Should we switch to a structured format, instead of current format
> that tools struggle to convert.
> >> >
> >> > Something that one could push into Solr would have been nice...
> >> >
> >> > Regards,
> >> > Alex
> >> >
> >> > On Mon., Nov. 23, 2020, 4:47 p.m. David Smiley, <dsmiley@apache.org>
> wrote:
> >> >>
> >> >> I pushed a commit to a PR for the prometheus exporter that includes
> a CHANGES.md
> >> >>
> https://github.com/apache/lucene-solr/pull/1972/commits/bec84ce2a1d60480ce0c54b78e83a70f83e7b058
> >> >> and likewise for a commit to a PR for the docker module:
> >> >>
> https://github.com/apache/lucene-solr/pull/2083/commits/540f8117153d12bd13441326035820f97084878a
> >> >>
> >> >> * I chose the Markdown format. This is an opportune time to
> switch. This meant changing "==== 9.0 ====" to "9.0" then "======" beneath
> it, but otherwise, no changes!
> >> >> * I chose to start this for 9.0. Any changes prior to 9.0 I think
> should continue to do things as we have been doing things historically.
> >> >> * I considered updating dev-tools/scripts/addVersion.py but
> ultimately elected not to. I think the rate of changes in each module will
> be low enough that it's not a big deal to maintain it manually. Plus, I
> confess I'm less motivated to touch Python ;-) but I'd be more than happy
> to see someone automate this.
> >> >>
> >> >> If this is agreeable, Solr's master CHANGES.txt ought to have
> references to CHANGES.md for contribs & Docker.
> >> >>
> >> >> ~ David Smiley
> >> >> Apache Lucene/Solr Search Developer
> >> >> http://www.linkedin.com/in/davidwsmiley
> >> >>
> >> >>
> >> >> On Mon, Nov 23, 2020 at 11:56 AM Houston Putman <
> houstonputman@gmail.com> wrote:
> >> >>>
> >> >>> +1
> >> >>>
> >> >>> I think that having separate CHANGES.txt files for the different
> parts of Solr would be great. If you are looking for certain changes you
> would generally know which module to go to.
> >> >>>
> >> >>>> Some items that have a more sweeping impact would be listed in both
> >> >>>
> >> >>>
> >> >>> I am ambivalent on having a separate CHANGES.txt for SolrJ, as long
> as major changes are included in the main CHANGES.txt. In general it's easy
> to add an entry to every applicable CHANGES.txt, no matter which module the
> change was made in.
> >> >>>
> >> >>> - Houston
> >> >>>
> >> >>> On Sat, Nov 21, 2020 at 1:34 AM David Smiley <dsmiley@apache.org>
> wrote:
> >> >>>>
> >> >>>> What of Docker changes? And beyond direct changes to Dockerfile +
> scripts, it could feature particular notable changes to the server that are
> particularly noteworthy... like hypothetical improvements to solr home /
> core root dir etc. configuration.
> >> >>>>
> >> >>>> Even if Contribs/Modules are not separated out of the repo *yet*
> (even if they hypothetically never leave), I think it's desirable to
> separate their CHANGES.txt in master now.
> >> >>>>
> >> >>>> RE SolrJ -- I know it's used heavily in the server side; this one
> is more debatable than the others and I don't have a strong opinion. Some
> items that have a more sweeping impact (e.g. HTTP2) would be listed in both
> but the difference is that the SolrJ side would have a more user-facing
> purpose, mentioning SolrClient subclasses that are pertinent to draw
> attention to compatibility or new classes users should know about. This
> kind of stuff is maybe too detailed to bother putting in
> solr-upgrade-notes.adoc but would not be to SolrJ's dedicated CHANGES.txt.
> On server CHANGES.txt, we tend to be vague. If SolrJ is changed for
> something that has more to do with server-side (e.g. SOLR-14691 "Metrics
> Reporting Should Avoid Creating Objects" which changed some utils in
> SolrJ), then it ought not to be listed in SolrJ's proposed CHANGES.txt.
> Admittedly there may be more cumulative CHANGES.txt maintenance between the
> two.
> >> >>>>
> >> >>>> ~ David Smiley
> >> >>>> Apache Lucene/Solr Search Developer
> >> >>>> http://www.linkedin.com/in/davidwsmiley
> >> >>>>
> >> >>>>
> >> >>>> On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <
> ichattopadhyaya@gmail.com> wrote:
> >> >>>>>
> >> >>>>> I think whatever we don't ship in the main tarball today should
> stay separate. Going forward, when we stop shoving the extra modules
> (contribs) into the main distro, we can separate out their changelogs.
> However, I feel SolrJ changes should stay with Solr changes since it is
> also used heavily in the server side.
> >> >>>>>
> >> >>>>> On Sat, 21 Nov, 2020, 3:39 am David Smiley, <dsmiley@apache.org>
> wrote:
> >> >>>>>>
> >> >>>>>> I was about to merge a PR pertaining to Solr's new Docker module
> when it occurred to me that I ought to add a CHANGES.txt entry. But, for
> Solr users (which includes me and everyone reading this), it's annoying to
> have to go to Solr's all-encompassing CHANGES.txt to find Docker upgrade
> notes, which is a distinct way of running Solr. I think the same could be
> said for our contribs, and perhaps even SolrJ, which is another distinct
> consumable. The idea of separated CHANGES.txt aligns well with contribs
> being further isolated (see both the discussion on separate git repos for
> them, and also the discussion of getting rid of "dist" (each contrib's jar
> goes in its own folder; keeps to itself)).
> >> >>>>>>
> >> >>>>>> Solr's root /CHANGES.txt could at the very top reference the
> other CHANGES.txt files.
> >> >>>>>>
> >> >>>>>> WDYT?
> >> >>>>>>
> >> >>>>>> ~ 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
> >>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>