Hi Oleg, As an outsider of HttpComponents, but with deep knowledge on site management with Maven, I'll try to give my view/analysis on this topic, hoping this will help your project do its own choices.
This is a classical topic: how to mix unversioned documentation content in a site that interacts well with component release documentation that is strongly versioned. This topic is classical, and there are multiple options that each come with their pros and cons: I never found a solution that has only advantages (be it with or without Maven). First, I'll point to a PR I just opened: https://github.com/apache/httpcomponents-website/pull/6 This removes the unmeaningfull "Version: 1-SNAPSHOT" in the breadcrumb of your current unversionned part of the site This will bring us to the key question: how to manage the transition: from unversioned content http://hc.apache.org/index.html to strictly versioned content (released with each component release) http://hc.apache.org/httpcomponents-client-4.5.x/project-info.html http://hc.apache.org/httpcomponents-client-5.0.x/project-info.html http://hc.apache.org/httpcomponents-core-4.4.x/project-info.html http://hc.apache.org/httpcomponents-core-5.0.x/project-info.html http://hc.apache.org/httpcomponents-core-5.1.x/project-info.html http://hc.apache.org/httpcomponents-asyncclient-4.1.x/project-info.html In your current structure, it works via an intermediate unversioned set of pages that mimic the list of components and their maintained branches at their latest released version: http://hc.apache.org/httpcomponents-client-4.5.x/index.html http://hc.apache.org/httpcomponents-client-5.0.x/index.html http://hc.apache.org/httpcomponents-core-4.4.x/index.html http://hc.apache.org/httpcomponents-core-5.0.x/index.html http://hc.apache.org/httpcomponents-core-5.1.x/index.html http://hc.apache.org/httpcomponents-asyncclient-4.1.x/index.html You have 3 components, and manage 2+3+1 branches: then in the intermediate part, on the 2 first components that have respectively 2 and 3 branches, you hand-maintain 2 and 3 copies of transitional content: https://github.com/apache/httpcomponents-website/tree/master/src/site/apt Notice that it looks like httpcomponents-asyncclient-4.0.x source directory could be dropped We can also look at equivalent generated html location: https://svn.apache.org/viewvc/httpcomponents/site/ Here we can find more content that has no associated source (httpcomponents-client-4.2.x/, httpcomponents-client-4.4.x/, httpcomponents-core-4.2.x/ and httpcomponents-core-4.3.x/) With the current setup we did with Michael, we kept this choice: it's not ideal from a Maven Site Plugin / Maven SCM Publish Plugin perspective (the svn checkout of unversioned html content cannot avoid to check out heavy component releases documentation). But it works IMHO sufficiently well: it won't scale if you add maby new components or new maintained branches, where the size of component releases documentation would become really too much). If you choose to keep this structure, there are some improvements I can propose to enhance consistency between intermediate content and component release documentation: we can work on this once decision is made. In Maven, we had this issue of many components: we have near 100. Then we had to put the limit between unversioned and versioned content somewhere else. I'll show concretely one example: skins, which is the most simple one. We have 5 skins, which have separate release cycle (it's the same with 30 plugins and 20 shared components...) Then our transition from unversioned to versioned html content is: https://maven.apache.org/skins/index.html which links to current latest releases https://maven.apache.org/components/skins/ (I won't show for now details on how it is done, let's keep is as simple as possible) One interesting aspect of this solution is that we also have the full history of each past release + the current LATEST that can be updated with current SNAPSHOT if we take time (which we don't usually, unless we want to see current documentation work in progress): https://maven.apache.org/components/skins-archives/ In HTTP Component project, we could have variants of Maven setup: you could have: unversioned components directories: http://hc.apache.org/httpcomponents-client/ http://hc.apache.org/httpcomponents-core/ http://hc.apache.org/httpcomponents-asyncclient/ containing versioned releases http://hc.apache.org/httpcomponents-client/4.5.0/ http://hc.apache.org/httpcomponents-client/4.5.1/ http://hc.apache.org/httpcomponents-client/5.0.0/ http://hc.apache.org/httpcomponents-client/5.0.x/ with some branches links: http://hc.apache.org/httpcomponents-client/4.5.x/ http://hc.apache.org/httpcomponents-client/5.0.x/ (I did not explain specific Maven core case, where we have such a structure https://maven.apache.org/ref/ with a "current" link: https://maven.apache.org/ref/current/ ) I don't know how many releases you want to do for now, nor when. If you don't add new components or maintained branches, you can continue with your current way of doing, and let more time before deciding to change anything I know this was a long email, but there is no easy magic solution: there are multiple solutions with pros and cons. Then it's all about understanding before deciding to move or not. You currently have a working solution, that IMHO only has a scaling issue: perhaps scaling is not a requirement for you. HTH Hervé Le vendredi 8 janvier 2021, 20:35:43 CET Oleg Kalnichevski a écrit : > Michael > > Were you able to make any progress in your work on web site publishing? > > I would like to start pushing javadoc and JApiCmp reports to the > artifact repository with all new releases. > > This would potentially make it possible to decouple the release process > and web site publishing and enable us to work with project specific > content without requiring a formal release and a release vote. > > Oleg > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
