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

[Sanne Grinovero]

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.

>
>
> Yoann Rodière
> Hibernate NoORM Team
> yoann at hibernate.org
>
> On 13 September 2017 at 11:48, Sanne Grinovero <sanne at hibernate.org> wrote:
>>
>> On 13 September 2017 at 10:41, Emmanuel Bernard <emmanuel at hibernate.org>
>> wrote:
>> > 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.
>>
>>  - having a "Downloads" link is essential
>>  - having a "Releases" page is what we think is more useful, for many
>> good reasons
>>
>> Yet we agree they are slightly different in nature. Could we ride the
>> differences and generate them both?
>>
>> Especially "Releases" could be a good home for all older releases and
>> the "Past Roadmaps" which Emmanuel suggested before we should have,
>> yet I said they don't belong on "Roadmap".
>> 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?
>>
>> Thanks,
>> Sanne
>>
>>
>> >
>> >>
>> >> 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
>> >>>>>>
>> >>>>>
>> >>>>>
>> >>>>>
>> >
>
>