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

Tue Sep 19 02:36:26 EDT 2017

So, following the comments and a discussion on Hangouts on Friday, I worked
a bit more, and I just pushed what will hopefully be the last version ;)

Main changes:

   - The "Releases" menu entry now has one sub-entry for each series
   - The big, green/yellow buttons related to the stable/development
   releases, and located on the top of the "About" page and "Releases" page.
   Previously they allowed to download a ZIP, but that's arguably not very
   useful without all the information provided by the series page
   (documentation, "What's new", compatibility, ...).
   So now, they redirect to the dedicated page of the current
   stable/development series.
   See for example http://staging.hibernate.org/ogm/
   - The list of series in the "Releases" page has been modified to better
   suit its new purpose: it's just a hub to the dedicated page of each series,
   and as such its content should be very clear and provide obvious links to
   the page for each series. I made do with what's available in our current
   CSS framework (it's Bootstrap 2, which is very old), but I have good hope
   that we could improve on that one day (if we upgrade to Bootstrap 3/4).
   See for example http://staging.hibernate.org/ogm/releases/
   - The maven coordinates and download link for the latest releases has
   moved to the series-specific page. It is configurable for each project: one
   can specify in the series.yml file which artifacts should be displayed, and
   add a summary for each artifact.
   I decided against the XML format and simply displayed the GAV as
   groupId:artifactId:version. Two reasons:
    1. The XML format is really, really verbose, and the pages are long
   enough as they are (one already needs to scroll one screen down to see the
   "What's new" section).
    2. I can't create a single syntax-highlighted block from the content of
   YAML files (if I switch to the AsciiDoc format, I don't have access to the
   loop features of HAML, and if I stick to HAML I don't have access to
   AsciiDoc syntax highlighting).
   Yes, we could probably solve 2, given enough time. And yes, I suppose we
   could find better UI alternatives using tabs or whatever. But I've already
   spent way too much time on this. Could we just agree it's good enough and
   work on this later?
   See for example http://staging.hibernate.org/search/releases/5.8/#get_it
   - As requested, I updated the "survival guide": http://staging.
   hibernate.org/survival-guide/

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

On 18 September 2017 at 10:44, Sanne Grinovero <sanne at hibernate.org> wrote:

> On 14 September 2017 at 13:34, Steve Ebersole <steve at hibernate.org> wrote:
> > Yoann,
> >
> > First thanks for the work on this.  I think it looks worlds better.  A
> few
> > minor things:
> >
> > Not sure of the source for this, but can we fix these doc link for 5.2
> from
> > `https://docs.jboss.org/hibernate/stable/orm/userguide/html_single/
> Hibernate_User_Guide.html`
> > to `https://docs.jboss.org/hibernate/orm/5.2`?  Also, why https?  Not
> sure
> > it matters, just found it odd
>
> Specifically about the `https` question: there's no longer any reason
> standing to avoid https, other than it being slightly more work to
> setup - in this case it's done by the jboss.org team so we can take
> advantage from it at no extra effort.
>
> There are several benefits in using it from the SEO perspective though
> so we should use and encourage it whenever possible, to make these
> URLs the canonical ones for the documentation. (and also because
> otherwise bots (and people) need to be thaught that this content is
> now available over https as well).
>
> Ideally we should set it up for our websites too.
>
> Thanks,
> Sanne
>
> > Much of the information on that ORM releases page is, in turn,
> > version/series specific.  Any reason why those pieces of information are
> not
> > part of the series?  Either in the synopsis on the releases page or on
> the
> > specific series page, or both.  Specifically
> >
> > "Compatibility Matrix" - the fact that its a table based on series is a
> good
> > indicator it is all series specific ;)
> > "Maven Repository" - I'd personally prefer to have this as part of the
> > series info
> >
> > I think the individual series pages are missing a key piece of
> > information... the "synopsis" of that series.  I guess partially this
> fits
> > under "what's new"
> >
> > Other than these minor things I love it.  Great job!
> >
> > P.S. another question is whether (and if so, how) to apply the same
> > treatment to the Documentation info in terms of the nav links.
> >
> > On Thu, Sep 14, 2017 at 7:05 AM Yoann Rodiere <yoann at hibernate.org>
> wrote:
> >>
> >> I polished the changes, applied them to all projects (ORM, OGM,
> Validator,
> >> Search), and sent a PR: https://github.com/hibernate/
> hibernate.org/pull/126
> >> Could you guys review it? Mainly I'd need one person per project to
> check
> >> they agree with the changes, especially in their project's section.
> >> Also, there's still a bit of work to do for each project, mainly filling
> >> in missing metadata (see the PR).
> >>
> >> Yoann Rodière
> >> Hibernate NoORM Team
> >> yoann at hibernate.org
> >>
> >> On 14 September 2017 at 10:38, Emmanuel Bernard <emmanuel at hibernate.org
> >
> >> wrote:
> >>>
> >>> On Wed 17-09-13 10:55, Sanne Grinovero wrote:
> >>>>
> >>>> On 13 September 2017 at 10:51, Yoann Rodiere <yoann at hibernate.org>
> >>>> wrote:
> >>>>>>
> >>>>>> 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.
> >>>>>
> >>>>>
> >>>>>
> >>>>> At least versions are in desc order :D
> >>>>> More seriously, I was more worried about the number of dependencies
> >>>>> than
> >>>>> about the number of series. We don't want to maintain a hundred
> >>>>> branches, so
> >>>>> we'll probably try to keep the number of series to a minimum, but we
> do
> >>>>> want
> >>>>> to offer as much as possible to users, so we may offer many different
> >>>>> integrations, and thus many different dependencies. Just think if the
> >>>>> ORM
> >>>>> team wants to display supported versions of each DBMS... So I thought
> >>>>> showing versions horizontally would be more future-proof.
> >>>>> I'll try to add horizontal scrolling to the table. The oldest
> releases
> >>>>> may
> >>>>> not be displayed, but then those are not the one we want to
> advertise,
> >>>>> so...
> >>>>> And in any case, we have limited horizontal space, so we have to hide
> >>>>> *something*.
> >>>>> About phones, I think bootstrap has something, I'll give it a try.
> >>>>>
> >>>>>> On "Downloads" we only want to promote the active branches; have
> some
> >>>>>> basic series descriptions but way more ecclectic than the releases
> >>>>>> descriptions. We make them cross-linked and everyone is happy?
> >>>>>
> >>>>>
> >>>>>
> >>>>> Sure, we can do that. But the "downloads" page will essentially be a
> >>>>> stripped-down version of the "releases" page.
> >>>>
> >>>>
> >>>> +1 since maintenance is automated I see no problem with a little
> >>>> redundancy.
> >>>
> >>>
> >>> I'm not sure two pages is really solving the problem. It looks like you
> >>> don't want to make a choice. But I don't have a pro/con opinion.
> >>> My real concern is since you will have two pages, what's the navigation
> >>> logic? How do you reach each on of these pages?
> >>>
> >>> Just thinking out loud here but I think the one way to solve long
> >>> standing Steve objective is indeed to have per series sections of the
> >>> website (including download, documentation, migration guide)
> >>> And a top nav for "latest/promoted" releases (like we have today
> >>> really).
> >>> How do you merge the two navigation wise is what I don't know.
> >>> This is for later work anyways.
> >>
> >>
> >
>
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>