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 yo...@hibernate.org On 8 September 2017 at 16:44, Yoann Rodiere <yo...@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 > yo...@hibernate.org > > On 8 September 2017 at 16:05, Steve Ebersole <st...@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 <sa...@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 <yo...@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 >>> > yo...@hibernate.org >>> > >>> > On 6 September 2017 at 17:16, Steve Ebersole <st...@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 <sa...@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 <yo...@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 >>> >>> > yo...@hibernate.org >>> >>> > >>> >>> > On 6 September 2017 at 09:21, Emmanuel Bernard < >>> emman...@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@lists.jboss.org >>> >>> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> >>> > _______________________________________________ >>> >>> > hibernate-dev mailing list >>> >>> > hibernate-dev@lists.jboss.org >>> >>> > https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> >>> >>> >>> _______________________________________________ >>> >>> hibernate-dev mailing list >>> >>> hibernate-dev@lists.jboss.org >>> >>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >>> > >>> > >>> >> > _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev