I definitly struggle with this. I wonder if we need a brand new approach that
isn’t encumbered by historical patterns to get us moving forward on this?
What if we changed it to something that focused on the different constituencies
of Solr.
* Changes Impacting Search Developers
* Changes Impacting Solr Operations Folks
* Changes Impacting Developers of Apache Solr
And maybe we pull the source information from the Github commit logs, Github
issues (if any), and the JIRA tickets and have someone just write it up? Heck,
I bet you paste all the text into GPT and it’ll give you a nice summary…. Add
that as a script.
If we want something more detail oriented, then we could machine generate a
dump of stuff and let users just go through it.
Maybe even a CHANGES.txt that is human written, and then CHANGES_9_7.txt that
is the machine dumped stuff.
David, I do appreciate your pushing forward on this…. Whatever we do, I hope we
document in our dev-docs/ what the expectations are for documenting changes so
the current folks and future committers all have something to reference ;-).
How can we move from bike shedding CHANGES.txt to something more concrete?
> On Jun 13, 2024, at 4:35 AM, David Smiley <dsmi...@apache.org> wrote:
>
> When I think of CHANGES.txt, I think of communicating to users. We
> write something succinct for the benefit of users to understand how
> this change will impact them.
>
> I don't think of CHANGES.txt as a log of all changes. I think
> increasing the scope to such wastes the time of users (and *we* are
> also users!), and dilutes the value of more meaningful entries.
>
> I know we have an "Other" section... perhaps this section allows us to
> add stuff that no user ought to care about. Not sure if users know to
> not waste their time looking at it. Still... I think we shouldn't
> bother adding some changes to CHANGES.txt at all.
>
> So... if a deprecated method is replaced with an equivalent... lets
> just not add this; okay? Specific example: replacing new URL("...")
> with the new equivalent. Honestly I don't even need to ask; just
> don't. Perhaps others have input on other examples or have different
> perspectives of thinking about this. The presence of a JIRA issue
> doesn't necessarily mean a CHANGES.txt entry needs to be added.
>
> ~ David Smiley
> Apache Lucene/Solr Search Developer
> http://www.linkedin.com/in/davidwsmiley
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@solr.apache.org
> For additional commands, e-mail: dev-h...@solr.apache.org
>
_______________________
Eric Pugh | Founder | OpenSource Connections, LLC | 434.466.1467 |
http://www.opensourceconnections.com <http://www.opensourceconnections.com/> |
My Free/Busy <http://tinyurl.com/eric-cal>
Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
<https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
This e-mail and all contents, including attachments, is considered to be
Company Confidential unless explicitly stated otherwise, regardless of whether
attachments are marked as such.
