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

Yoann Rodiere yoann at hibernate.org
Fri Sep 8 11:54:43 EDT 2017 

Following Steve's comments, I made another few changes for the sake of
usability:

   - Moved the series-specific pages so that the path is more consistent
   with ORM documentation; the series-specific page for Search 5.8, for
   instance, is now http://staging.hibernate.org/search/releases/5.8/
   - Changed the list of releases in the "releases" page: renamed "Latest
   releases" to "Maintained series", and made the series version more
   prominent, on the left, while the latest release version is a bit less
   prominent, on the right. That way the list should be a bit less confusing.
   - Added links to the reference from the "Releases" page:
   http://staging.hibernate.org/search/releases/
   - Added a hero-unit at the top of the series-specific pages, with a few
   links: http://staging.hibernate.org/search/releases/5.8/


Yoann Rodière
Hibernate NoORM Team
yoann at hibernate.org

On 8 September 2017 at 16:44, Yoann Rodiere <yoann at hibernate.org> wrote:

> Steve,
>
> If I understood correctly, the main difference between what I did and what
> you want is you don't want a "hub" pointing to different versions, you want
> to redirect to the page for the latest version, and from there allow to
> move to another version using drop-down.
> While I can understand you'd want that for ORM, I'm not sure it's such a
> good idea for projects such as Search or OGM, where the difference between
> two families is not only about features, but also (and in some cases,
> mainly) about which versions of other components it can integrate with. In
> this case, I'm not sure a drop-down would be enough to guide users to the
> correct version...
>
> As for your other concerns:
>
>    - I'll try to add a links to the "documentation" page specific to each
>    series, both in the main "releases" page and in each series-specific page.
>    - The list of all micro/bugfix releases is already there, at the
>    bottom of the page: http://staging.hibernate.org/search/releases/5.8/
>    I'll see if I can add some sort of table of contents at the top to
>    make it more visible.
>    - The link to the full changelog is already there, though maybe it's
>    not very visible.
>
>
> Yoann Rodière
> Hibernate NoORM Team
> yoann at hibernate.org
>
> On 8 September 2017 at 16:05, Steve Ebersole <steve at hibernate.org> wrote:
>
>> For me the real problem is that its not just Downloads/Releases that
>> should be (need to be really) treated in this manner - our documentation is
>> also family specific.
>>
>> So for ORM I had envisioned a "versions" (although "releases" works just
>> as well) component to the url scheme.  Vlad did this for documentation (see
>> the version drop down), but we have not yet tackled this for versions - too
>> many other more pressing tasks.  Also, I am not sure yet the best overall
>> structure for this - some of the project related information is not
>> version-specific (FAQ, Books, Paid Support, etc) while others are.
>>
>> To me personally, I think the "Documentation" and
>> Downloads/Versions/Releases should not be on the left nav.  Or, leave them
>> on the nav and have them implicitly direct to the
>> most-recent-prod-release-family.  But overall I had envisioned a
>> release-specific page - specific to release families (5.0, 5.1, etc) as
>> opposed to specific micro/bugfix releases (5.0.1, 5.0.2, etc).  This
>> release page would include:
>>
>>    1. General description - what were the main points or developments
>>    for this family?
>>    2. Links to its documentation
>>    3. List of all micro/bugfix releases as a sort-of simplified
>>    changelog.  This part is still unclear in my head as to the best way to
>>    represent this information, but ultimately each entry in this list would
>>    need to include:
>>       1. announcement URL
>>       2. sysopsis of the main fixes/changes
>>       3. link to the full changelog
>>
>> For the most part, the information I listed for the micro/bugfix release
>> entries is covered in the release announcement so one option is to simply
>> link to each announcement for that family - possibly driven by the release
>> yaml files.
>>
>> This also fixes what I find to be a very confusing list of "latest"
>> releases.  I think that works much better as a single entry on the release
>> family page.
>>
>> Will what you did "work" for ORM?  Sure.  What I describe is just what I
>> personally think would be better in terms of ORM needs, but I have
>> absolutely no resources to do that atm.  So for now, whatever y'all deem is
>> best is probably the best way to go.
>>
>>
>> On Fri, Sep 8, 2017 at 8:11 AM Sanne Grinovero <sanne at hibernate.org>
>> wrote:
>>
>>> Thanks Yoann!
>>> Looks great.
>>>
>>> Two minor suggestions:
>>>  - could the two links we have for each release on search/releases/ on
>>> two separate lines? Or something else to make it clear that there are
>>> two linkes.
>>>  - Regarding the "Compatibility matrix", the header line (the one in
>>> black) .. I think we need to clarify in some way that you're referring
>>> to Hibernate Search releases. Possibly just link to the page
>>> describing the family?
>>>
>>> Thanks,
>>> Sanne
>>>
>>>
>>> On 8 September 2017 at 13:53, Yoann Rodiere <yoann at hibernate.org> 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-Guide---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/do
>>> wnloads/ <
>>> >>> >> 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/ro
>>> admap/ <
>>> >>> >> 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/hibernat
>>> e-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