You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Oleg Kalnichevski <ol...@apache.org> on 2021/01/08 19:35:43 UTC
Publishing reports to the artifact repository with new releases
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: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Publishing reports to the artifact repository with new releases
Posted by Hervé BOUTEMY <he...@free.fr>.
Le samedi 9 janvier 2021, 19:33:42 CET Oleg Kalnichevski a écrit :
...
> > since we did the work in november, you have this, isn't it?
>
> Yes, pretty much, but what I understood from what Michael has said, you
> intend to start moving non-versioned content from the main website
> projects to individual projects (sub-projects). This does not sound
> right to me.
ok, now I perfectly understand what you're talking about
Don't worry, I keep this in mind in every proposition and make explicit if at
any time there is a move of content from unversioned (then unreleased, then
unvoted) to versioned (then released, then voted)
...
> > I understand that my explanations seem theoretical and hard to
> > really
> > evaluate.
> > This can be tested easily without breaking the current setup, but by
> > adding
> > normal documentation fir the current SNAPSHOT: if you trust me, I can
> > work with
> > Michael to show that
> >
> > Are you interested?
>
> I still do not quite what exactly you intend to do but whatever
> approach you take, as long as we do not need a formal release to
> publish non-versioned content, I would be interested to see it.
ok, I'll provide PRs and instrutions to test this scenario: I'm confident it
will help us better understand each other and improve things
Regards,
Hervé
>
> Oleg
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Publishing reports to the artifact repository with new releases
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2021-01-09 at 18:59 +0100, Hervé BOUTEMY wrote:
> Le samedi 9 janvier 2021, 12:53:04 CET Oleg Kalnichevski a écrit :
> > On Sat, 2021-01-09 at 10:09 +0100, Hervé BOUTEMY wrote:
> > > Hi Oleg,
> >
> > ...
> >
> > > 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.
> >
> > Hi Hervé
> >
> > Thank you so much for helping us and sharing your knowledge and
> > experience with us. It is truly appreciated.
> >
> > The only important objective for me is to ensure that update and
> > deployment of non-versioned content should not require a formal
> > release
> > and a release vote and ideally could be done by raising a PR with
> > the
> > website project by an external contributor.
> since we did the work in november, you have this, isn't it?
>
Yes, pretty much, but what I understood from what Michael has said, you
intend to start moving non-versioned content from the main website
projects to individual projects (sub-projects). This does not sound
right to me.
> > I personally think publishing release (version) specific content
> > (project reports) to the artifact repository during a formal
> > release is
> > a very simple, practical, cheap and conceptually clean solution to
> > the
> > project, so I do not quite understand an aversion to this idea.
> Ok I lost you with too many explanations.
> I'll explain more in details the issues with the current setup.
> Apart from the scalability issue, if in the future you added many
> components
> or many branches...
>
> Currently, in the versioned content, you have a multi-module site
> that is
> quite non-functionnal, because of the intermediate files stored in
> the same
> directory.
> Example:
> http://hc.apache.org/httpcomponents-core-5.1.x/project-reports.html
> If you follow links from the left "Modules" menu, the links point to
> "Not
> Found" index.html: if you remove the last "index.html", you see the
> module
> content.
>
> If we look at svn view
> https://svn.apache.org/viewvc/httpcomponents/site/httpcomponents-client-5.0.x/
>
> The root cause is that this directory is supposed to be the
> httpcomponents-client release documentation, but it also contains
> some unversioned content (=
> with "svn-site-role" Author)
>
> If we simply clearly split the versioned release documentation from
> the
> unversioned content, it would make things much more clean and we
> could improve
> the release documentation
> Like having the release documentation in
> http://hc.apache.org/httpcomponents-core-5.1.x/doc
>
>
> I understand that my explanations seem theoretical and hard to
> really
> evaluate.
> This can be tested easily without breaking the current setup, but by
> adding
> normal documentation fir the current SNAPSHOT: if you trust me, I can
> work with
> Michael to show that
>
> Are you interested?
>
I still do not quite what exactly you intend to do but whatever
approach you take, as long as we do not need a formal release to
publish non-versioned content, I would be interested to see it.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Publishing reports to the artifact repository with new releases
Posted by Hervé BOUTEMY <he...@free.fr>.
Le samedi 9 janvier 2021, 12:53:04 CET Oleg Kalnichevski a écrit :
> On Sat, 2021-01-09 at 10:09 +0100, Hervé BOUTEMY wrote:
> > Hi Oleg,
>
> ...
>
> > 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.
>
> Hi Hervé
>
> Thank you so much for helping us and sharing your knowledge and
> experience with us. It is truly appreciated.
>
> The only important objective for me is to ensure that update and
> deployment of non-versioned content should not require a formal release
> and a release vote and ideally could be done by raising a PR with the
> website project by an external contributor.
since we did the work in november, you have this, isn't it?
>
> I personally think publishing release (version) specific content
> (project reports) to the artifact repository during a formal release is
> a very simple, practical, cheap and conceptually clean solution to the
> project, so I do not quite understand an aversion to this idea.
Ok I lost you with too many explanations.
I'll explain more in details the issues with the current setup.
Apart from the scalability issue, if in the future you added many components
or many branches...
Currently, in the versioned content, you have a multi-module site that is
quite non-functionnal, because of the intermediate files stored in the same
directory.
Example: http://hc.apache.org/httpcomponents-core-5.1.x/project-reports.html
If you follow links from the left "Modules" menu, the links point to "Not
Found" index.html: if you remove the last "index.html", you see the module
content.
If we look at svn view
https://svn.apache.org/viewvc/httpcomponents/site/httpcomponents-client-5.0.x/
The root cause is that this directory is supposed to be the httpcomponents-client release documentation, but it also contains some unversioned content (=
with "svn-site-role" Author)
If we simply clearly split the versioned release documentation from the
unversioned content, it would make things much more clean and we could improve
the release documentation
Like having the release documentation in
http://hc.apache.org/httpcomponents-core-5.1.x/doc
I understand that my explanations seem theoretical and hard to really
evaluate.
This can be tested easily without breaking the current setup, but by adding
normal documentation fir the current SNAPSHOT: if you trust me, I can work with
Michael to show that
Are you interested?
Regards,
Hervé
>
> Oleg
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Publishing reports to the artifact repository with new releases
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2021-01-09 at 10:09 +0100, Hervé BOUTEMY wrote:
> Hi Oleg,
>
>
...
>
> 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.
>
Hi Hervé
Thank you so much for helping us and sharing your knowledge and
experience with us. It is truly appreciated.
The only important objective for me is to ensure that update and
deployment of non-versioned content should not require a formal release
and a release vote and ideally could be done by raising a PR with the
website project by an external contributor.
I personally think publishing release (version) specific content
(project reports) to the artifact repository during a formal release is
a very simple, practical, cheap and conceptually clean solution to the
project, so I do not quite understand an aversion to this idea.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Publishing reports to the artifact repository with new releases
Posted by Hervé BOUTEMY <he...@free.fr>.
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: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org