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

Fri Sep 8 10:05:25 EDT 2017

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/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
> >
> >
>