[hibernate-dev] [Search and more] What is new in a give release

Emmanuel Bernard emmanuel at hibernate.org
Wed Sep 13 05:41:01 EDT 2017 

On Tue 17-09-12 13:50, Yoann Rodiere wrote:
>>
>> - Releases speaks less than downloads, Where do I download Hibernate X
>>  is a question we want addressed from the top level menus
>>
>
>Always amazed that there's still people out there actually downloading JARs
>manually. But yes, we shouldn't forget about them.
>
>My problem with "downloads" is that, while it conveys the correct meaning
>for the minority (I hope) of users not using Maven/Gradle, it's really not
>appropriate as an entry point to pages giving information about
>series/releases.
>Let's put it that way:
>
>   - To a user looking for info about a particular release (maven GAV,
>   changelog, ...) , a "download" entry isn't even remotely relevant
>   - To a user looking to download packages, a "releases" entry does seem a
>   bit relevant

You are right on principle. But if you look around, pretty much all
software websites have a download button leading to a page where you can
find releases, changelog etc. People are trained.

http://kafka.apache.org/downloads
http://struts.apache.org/download.cgi#struts2513
http://vertx.io/download/


Spring is the exception but they have one big page for everything per
project. Not what we want.
And GitHub which has Releases https://github.com/google/guava

I'm still not recovered from GitHub's move from Downloads to Releases to
be honest.

If everyone thinks Releases is clearer and more intuitive, I won't
block.

>
>But if you really want a "download" entry in the menu... would it be okay
>if it just redirected to the "releases" page? I'll do that for now.
>
>- if you do downloads -> releases, you need to also write some redirect
>>  rules not to break URLs
>>
>
>I already did. Redirects don't seem to work locally for some reason,
>though. They work on staging.
>
>
>> - I don't like the term maintained much, I think latest like you
>>  proposed makes it more neutral. You could even just name them Series
>>
>
>Steve found "latest releases" "confusing" (if I understood correctly). I
>changed it to "Series" as you suggested.
>
>
>> - The migration guide should probably be referenced from each individual
>>  series page.
>>
>
>Done.
>
>
>> - the matrix does not scale very well to that many versions.
>>
>
>Could you be more specific? Is it that you're having trouble finding out
>which cell relates to which HSearch version, or which cell relates to which
>dependency, or about the size of columns not being the same, or... ? I'd
>rather know exactly what's wrong before trying to mess with the CSS,
>because solutions to each of these problems will probably require to use
>more horizontal space, and as you can see we don't have that much available.

It's more the number of columns, what if you add more version, should I
scroll horizontally? Also releeases tend to be shown vertically with
version in desc order. This model breaks a bit this habit.

It does not work well on phones either.


>
>
>> - in the dedicated series page, "Reference" is confusing, I'd probably
>>  replace it with documentation or main documentation
>
>
>Done.
>
>Since there seems to be a general agreement that it's not worse than it
>used to be, I'll send a PR soon. We can continue the discussion there.
>
>
>
>Yoann Rodière
>Hibernate NoORM Team
>yoann at hibernate.org
>
>On 11 September 2017 at 15:54, Emmanuel Bernard <emmanuel at hibernate.org>
>wrote:
>
>> Hey Yoann and all,
>>
>> Thanks Yoann for stepping up. This is definitely much better.
>> Here are non ordered comments:
>>
>> - Releases speaks less than downloads, Where do I download Hibernate X
>>  is a question we want addressed from the top level menus
>> - if you do downloads -> releases, you need to also write some redirect
>>  rules not to break URLs
>> - I don't like the term maintained much, I think latest like you
>>  proposed makes it more neutral. You could even just name them Series
>> - The migration guide should probably be referenced from each individual
>>  series page.
>> - the matrix does not scale very well to that many versions.
>> - in the dedicated series page, "Reference" is confusing, I'd probably
>>  replace it with documentation or main documentation
>>
>> Emmanuel
>>
>> On Fri 17-09-08 14:53, Yoann Rodiere wrote:
>>
>>> Hey,
>>>
>>> I pushed an update to staging. I only converted the "Search" part for now.
>>> What changes:
>>>
>>>   - The _data folder structured changed a bit, so that we can introduces a
>>>   YAML file for each series (5.5, 5.6, 5.6, 5.8, ...), containing a
>>> summary
>>>   of this series and a list of integration constraints (ORM > 5.2, etc.)
>>>   - The "Downloads" page is renamed to "Releases", since, well, it's about
>>>   more than just downloads. See
>>>   http://staging.hibernate.org/search/releases/
>>>   - The "Releases" page now includes a "Compatibilty matrix" section based
>>>   on the new data I mentioned above
>>>   - The "Releases" page now includes links to one page for each series
>>>   ("More on the 5.8 series")
>>>   - There is now one page for each series (see
>>>   http://staging.hibernate.org/search/releases/series/5.8/). This page
>>>   includes:
>>>      - A short (one-line) summary of this series
>>>      - A reminder of the integration constraints for this series
>>>      - A section about the main changes in this release. I only wrote
>>>      something for the 5.8 series for now, and I basically
>>> copy/pasted sections
>>>      from various blog posts.
>>>      - A list of all releases in this series.
>>>
>>> What I didn't do, but could make sense:
>>>
>>>   - add a sub-menu element under "Releases" for each series
>>>   - link to the documentation for each of the latest releases from the
>>>   "Releases" page
>>>   - link to the latest documentation and to the migration guides from each
>>>   series' page
>>>
>>> What do you all think? Emmanuel, would this address your concerns? Steve,
>>> would this be a good fit for ORM?
>>>
>>> Yoann Rodière
>>> Hibernate NoORM Team
>>> yoann at hibernate.org
>>>
>>> On 6 September 2017 at 17:16, Steve Ebersole <steve at hibernate.org> wrote:
>>>
>>> This is something I brought up ages ago wrt ORM.  I wanted something
>>>> (although ideally integrated with the "more version friendly"
>>>> hibernate.org design) similar to what I did atm on the ORM GitHub wiki.
>>>> For example, for 5.2 we have:
>>>>
>>>>
>>>>    - https://github.com/hibernate/hibernate-orm/wiki/Roadmap5.2
>>>>    - https://github.com/hibernate/hibernate-orm/wiki/Migration-Gu
>>>> ide---5.2
>>>>    - https://github.com/hibernate/hibernate-orm/wiki/ReleaseNotes5.2
>>>>
>>>>
>>>>
>>>> The format could be better and some of this information could be combined
>>>> (release notes and migration guide e.g.).  But bear in mind that this was
>>>> just what I put together to illustrate what I was wanted to do, generally
>>>> speaking - so its a bit "rough"
>>>>
>>>>
>>>> On Wed, Sep 6, 2017 at 4:17 AM Sanne Grinovero <sanne at hibernate.org>
>>>> wrote:
>>>>
>>>> Thanks for that Emmanuel.
>>>>>
>>>>> I'll fix the one-liner describing the release, I believe we had
>>>>> already noticed this in the past: they need to describe the whole
>>>>> minor not the micro update.
>>>>> The Search roadmap actually also needs a little re-touch, I'll propose
>>>>> a PR for that too.
>>>>>
>>>>> Regarding past roadmaps: I don't like to clutter the roadmap page with
>>>>> the previous copies, especially as they should have a different nature
>>>>> of not being a plan but being a record of what was actually done.
>>>>> Also, we did agree in past meetings to remove all the old ones. e.g.
>>>>> we never ported the release notes for version 3.x and 4.x as back then
>>>>> we decided this was no place for that. Happy to revisit this decision
>>>>> but let's separate them:
>>>>>
>>>>> What about a "past releases" page at the same level of roadmap, and
>>>>> linking to it both from the main Search menu and the roadmap?
>>>>>
>>>>> +1 for Yoann's proposal to re-introduce the compatibility matrix
>>>>> (there was one ~6 years ago). I also had proposed to reintroduce it
>>>>> more recently, and was not done on the grounds that it gets out of
>>>>> date quickly.
>>>>> Still users badly need it so unless someone has a better idea, let's
>>>>> agree on trying to keep it up to date manually. Let's try structure it
>>>>> in such a way that it won't need to be updated for every single
>>>>> release.
>>>>>
>>>>> Thanks,
>>>>> Sanne
>>>>>
>>>>>
>>>>> On 6 September 2017 at 08:37, Yoann Rodiere <yoann at hibernate.org>
>>>>> wrote:
>>>>> > Hey,
>>>>> >
>>>>> > About Search, true, the information is somewhat hidden in many blog
>>>>> posts.
>>>>> > I'm not sure the roadmap is the right place, though, since we probably
>>>>> want
>>>>> > the format to be different for past and future releases: information
>>>>> for
>>>>> > past releases is typically more precise and more verbose, with code
>>>>> > examples and so on. See for instance this blog post:
>>>>> http://in.relation.to/
>>>>> > 2017/06/13/hibernate-search-5-8-0-Beta3/ . I'm afraid the future
>>>>> roadmap
>>>>> > would be drowned in the past releases.
>>>>> >
>>>>> > I was thinking about another problem: we don't have a compatibility
>>>>> matrix.
>>>>> > We only have a few dependencies (mainly ORM and Lucene), but it's
>>>>> really
>>>>> > hard to know which versions of the dependencies to use with which
>>>>> version
>>>>> > of Search, and users frequently use the wrong versions.
>>>>> > With that in mind, I would rather see a "Versions" page, with a
>>>>> summary
>>>>> at
>>>>> > the top (including a one-liner for each minor and the compatibilty
>>>>> matrix),
>>>>> > and one section for each minor (with anchors, so that we can link to
>>>>> them
>>>>> > from other pages such as the downloads). Or maybe even one page for
>>>>> the
>>>>> > detail of each minor, if there's too much text.
>>>>> > I think it would make sense to have all that information gathered in a
>>>>> > single place, because all of that is needed for users to pick the
>>>>> version
>>>>> > they want: they need to know the benefits of upgrading (features) but
>>>>> also
>>>>> > the constraints (compatibility matrix).
>>>>> > Maybe I can give it a try at the end of the week?
>>>>> >
>>>>> >
>>>>> > Yoann Rodière
>>>>> > Hibernate NoORM Team
>>>>> > yoann at hibernate.org
>>>>> >
>>>>> > On 6 September 2017 at 09:21, Emmanuel Bernard <
>>>>> emmanuel at hibernate.org>
>>>>> > wrote:
>>>>> >
>>>>> >> Hey all,
>>>>> >>
>>>>> >> I was trying to answer the following question, what is roughly new
>>>>> between
>>>>> >> 5.6, 5.7 and 5.8 (minor releases)?
>>>>> >>
>>>>> >> My first reflex was to go to http://hibernate.org/search/downloads/
>>>>> <
>>>>> >> http://hibernate.org/search/downloads/> to read about the onliner
>>>>> per
>>>>> >> release. Except it’s a onliner per micro release and “minor
>>>>> adjustments”
>>>>> >> for 5.6.3.Final gave me literally no info whatsoever.
>>>>> >>
>>>>> >> My second reflex was to go to http://hibernate.org/search/roadmap/ <
>>>>> >> http://hibernate.org/search/roadmap/> to find a historical entry
>>>>> about
>>>>> >> older versions and the main changes in bullet points. No luck. It
>>>>> only
>>>>> >> talks about the future.
>>>>> >>
>>>>> >> My third reflex was to go to http://in.relation.to/hibernate-search/
>>>>> <
>>>>> >> http://in.relation.to/hibernate-search/> I ended up giving up midway
>>>>> page
>>>>> >> 2 of the list of blog entries. It’s a mix of simultaneous parallel
>>>>> releases
>>>>> >> with what’s new since the last CR or the last micro kind of reports
>>>>> and
>>>>> >> gave up in dismay at the energy I would have to spend to extract
>>>>> what’s new
>>>>> >> for a full minor release.
>>>>> >>
>>>>> >> I did exaggerate a bit the third point but I did give up. We need
>>>>> >> somewhere a summary page of what’s new per minor releases. I think
>>>>> the
>>>>> >> roadmap page could be the host.
>>>>> >> Likewise, we might need a oneliner entry in the download section (per
>>>>> >> release) that points to this minor release summary.
>>>>> >>
>>>>> >> Thoughts?
>>>>> >>
>>>>> >> Speaking of roadmap:
>>>>> >> - HV roadmap is massively out of date
>>>>> >> - OGM is lying a bit on the future but at least has the past summary
>>>>> I
>>>>> was
>>>>> >> talking about
>>>>> >> - Search has a good future roadmap but no past
>>>>> >>
>>>>> >> Emmanuek
>>>>> >> _______________________________________________
>>>>> >> hibernate-dev mailing list
>>>>> >> hibernate-dev at lists.jboss.org
>>>>> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>>>> > _______________________________________________
>>>>> > hibernate-dev mailing list
>>>>> > hibernate-dev at lists.jboss.org
>>>>> > https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>>>>
>>>>> _______________________________________________
>>>>> hibernate-dev mailing list
>>>>> hibernate-dev at lists.jboss.org
>>>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>>>>
>>>>
>>>>
>>>>

More information about the hibernate-dev mailing list