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

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(a)hibernate.org On 8 September 2017 at 16:05, Steve Ebersole <steve(a)hibernate.org&gt; 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(a)hibernate.org&gt; > 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(a)hibernate.org&gt; 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(a)hibernate.org >> > >> > On 6 September 2017 at 17:16, Steve Ebersole <steve(a)hibernate.org&gt; >> 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(a)hibernate.org&gt; >> >> 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(a)hibernate.org&gt; >> 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(a)hibernate.org >> >>> > >> >>> > On 6 September 2017 at 09:21, Emmanuel Bernard < >> emmanuel(a)hibernate.org&gt; >> >>> > 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(a)lists.jboss.org >> >>> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> >>> > _______________________________________________ >> >>> > hibernate-dev mailing list >> >>> > hibernate-dev(a)lists.jboss.org >> >>> > https://lists.jboss.org/mailman/listinfo/hibernate-dev >> >>> >> >>> _______________________________________________ >> >>> hibernate-dev mailing list >> >>> hibernate-dev(a)lists.jboss.org >> >>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > >> > >> >