[hibernate-dev] [Search and more] What is new in a give release
Yoann Rodiere
yoann at hibernate.org
Tue Sep 12 07:50:13 EDT 2017
>
> - 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
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.
> - 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