Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

David Smiley
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
Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

Ishan Chattopadhyaya
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, <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

David Smiley
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


On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <[hidden email]> 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, <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

Houston Putman
+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 <[hidden email]> 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


On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <[hidden email]> 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, <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

David Smiley
I pushed a commit to a PR for the prometheus exporter that includes a CHANGES.md
and likewise for a commit to a PR for the docker module:

* 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


On Mon, Nov 23, 2020 at 11:56 AM Houston Putman <[hidden email]> 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 <[hidden email]> 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


On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <[hidden email]> 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, <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

Alexandre Rafalovitch
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, <[hidden email]> wrote:
I pushed a commit to a PR for the prometheus exporter that includes a CHANGES.md
and likewise for a commit to a PR for the docker module:

* 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


On Mon, Nov 23, 2020 at 11:56 AM Houston Putman <[hidden email]> 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 <[hidden email]> 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


On Fri, Nov 20, 2020 at 9:17 PM Ishan Chattopadhyaya <[hidden email]> 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, <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

Alexandre Rafalovitch
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 <[hidden email]> 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, <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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, <[hidden email]> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

David Smiley
I'd rather not scope-creep my proposal here further.  Granted I ventured into TXT -> Markdown.  

~ David Smiley
Apache Lucene/Solr Search Developer


On Tue, Nov 24, 2020 at 9:37 AM Alexandre Rafalovitch <[hidden email]> 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 <[hidden email]> 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, <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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, <[hidden email]> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

Alexandre Rafalovitch
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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, <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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, <[hidden email]> 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: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr: Separate CHANGES.txt for Docker, SolrJ, Contribs, ...

David Smiley
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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, <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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, <[hidden email]> 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: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]