You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Hervé BOUTEMY <he...@free.fr> on 2021/01/30 17:16:11 UTC
website + releases documentation publication structure
Hi,
As promised, here is an explanation of where we are and where we go next.
HttpCore and HttpClient have been updated to publish their documentation generated from source to:
http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST and
http://hc.apache.org/components/httpcomponents-client-5.0.x/LATEST
At any time, during SNAPSHOT development or at release staging time, documentation can be:
1. generated from source code: mvn site site:stage
2. then published to LATEST directory: mvn scm-publish:publish-scm
by any team member (once initial directory creation in svn will be ok [1])
Integration of this documentation to the main site requires to merge next PR:
https://github.com/apache/httpcomponents-website/pull/9
It will create symbolic links that will inject content in normal website directories (without the "/components/" parts that seems strange, explanation will follow...)
When you'll do a release, the release manager will publish the documentation and provide "LATEST" url, for review during the vote.
Once the vote will be ok, the state of the staging documentation will have to be marked as a release: this will be done with a "svn cp" command, like shown in the website PR [2]
Why this components/ directory?
The html website consists of the main website "unversioned" content and the documentation generated from source (LATEST and every release that the project will want to keep online).
If you build unversioned website and look at "target/site", you'll see that the content is 1,112 kB for 75 files.
But if you look at the content in svn [3], there are currently 51,740 files for 1,071,288 kB: there is documentation for each component branch, and that documentation will grow in the future with LATEST and every release
Then the website publication job on Jankins [4] will in the future svn checkout more and more content to update only these 75 files that are the unversioned content.
Separating documentation in a separate directory of the site is a first step to fix this scalability issue: in a second step, we'll move this svn directory to a location that is fully separate, then won't be checked out by website publication job.
I hope this explanation helps everybody understand how release documentation will be published easily and kept as much as you need.
Regards,
Hervé
[1] https://github.com/apache/httpcomponents-client/pull/280
[2] https://github.com/apache/httpcomponents-website/pull/9/files#diff-750296db9b9b33a71f10fa5eda497d2aabe583aad8be1b87a5ea2bb89957bcdf
[3] https://svn.apache.org/repos/asf/httpcomponents/site/
https://svn.apache.org/viewvc/httpcomponents/site/
[4] https://ci-builds.apache.org/job/HttpComponents/job/HttpComponents%20Website/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
ok: Fluido skin switch and edit button added to PR
https://github.com/apache/httpcomponents-website/pull/9
regards,
Hervé
Le mardi 2 février 2021, 10:52:59 CET Oleg Kalnichevski a écrit :
> On Tue, 2021-02-02 at 10:12 +0100, Michael Osipov wrote:
> > Am 2021-02-02 um 09:55 schrieb Oleg Kalnichevski:
> > > On Tue, 2021-02-02 at 08:32 +0100, Hervé BOUTEMY wrote:
> > > > Le dimanche 31 janvier 2021, 10:03:44 CET Oleg Kalnichevski a
> > > >
> > > > écrit :
> > > > > > One useful thing that we can do is adding "edit" icon like we
> > > > > > have on
> > > > > > the
> > > > > > Maven website, the little icon in breadcrumb:
> > > > > > https://maven.apache.org/
> > > > > > This would ease finding the source file from a page, then
> > > > > > edit
> > > > > > easily
> > > > > > in Github
> > > > > > (eventually forking to create a PR). From Maven experience,
> > > > > > it
> > > > > > eases
> > > > > > things a
> > > > > > lot both for contributors (who don't know details), but even
> > > > > > for
> > > > > > seasoned
> > > > > > developers, who know, but find it cumbersome to find the
> > > > > > source.
> > > > > > WDYT?
> > > > >
> > > > > Yes, that would be great.
> > > >
> > > > I will need to update
> > > > https://svn.apache.org/viewvc/httpcomponents/maven-skin/trunk/
> > > >
> > > > Do you want to do it on Subversion, or do you prefer to switch to
> > > > Git
> > > > first?
> > >
> > > Yes, please. Switching it to Git would great.
> >
> > I have raised the question about our skin some time ago. The
> > concensus
> > was to drop it altogether and use Fluido at most with a few CSS
> > modifications.
> >
> > Does my memory serve me well?
>
> It does. Sorry for causing the confusion.
>
> 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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2021-02-02 at 10:12 +0100, Michael Osipov wrote:
> Am 2021-02-02 um 09:55 schrieb Oleg Kalnichevski:
> > On Tue, 2021-02-02 at 08:32 +0100, Hervé BOUTEMY wrote:
> > > Le dimanche 31 janvier 2021, 10:03:44 CET Oleg Kalnichevski a
> > > écrit :
> > > > > One useful thing that we can do is adding "edit" icon like we
> > > > > have on
> > > > > the
> > > > > Maven website, the little icon in breadcrumb:
> > > > > https://maven.apache.org/
> > > > > This would ease finding the source file from a page, then
> > > > > edit
> > > > > easily
> > > > > in Github
> > > > > (eventually forking to create a PR). From Maven experience,
> > > > > it
> > > > > eases
> > > > > things a
> > > > > lot both for contributors (who don't know details), but even
> > > > > for
> > > > > seasoned
> > > > > developers, who know, but find it cumbersome to find the
> > > > > source.
> > > > > WDYT?
> > > >
> > > > Yes, that would be great.
> > > I will need to update
> > > https://svn.apache.org/viewvc/httpcomponents/maven-skin/trunk/
> > >
> > > Do you want to do it on Subversion, or do you prefer to switch to
> > > Git
> > > first?
> > >
> >
> > Yes, please. Switching it to Git would great.
>
> I have raised the question about our skin some time ago. The
> concensus
> was to drop it altogether and use Fluido at most with a few CSS
> modifications.
>
> Does my memory serve me well?
>
It does. Sorry for causing the confusion.
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: website + releases documentation publication structure
Posted by Michael Osipov <mi...@apache.org>.
Am 2021-02-02 um 09:55 schrieb Oleg Kalnichevski:
> On Tue, 2021-02-02 at 08:32 +0100, Hervé BOUTEMY wrote:
>> Le dimanche 31 janvier 2021, 10:03:44 CET Oleg Kalnichevski a écrit :
>>>> One useful thing that we can do is adding "edit" icon like we
>>>> have on
>>>> the
>>>> Maven website, the little icon in breadcrumb:
>>>> https://maven.apache.org/
>>>> This would ease finding the source file from a page, then edit
>>>> easily
>>>> in Github
>>>> (eventually forking to create a PR). From Maven experience, it
>>>> eases
>>>> things a
>>>> lot both for contributors (who don't know details), but even for
>>>> seasoned
>>>> developers, who know, but find it cumbersome to find the source.
>>>> WDYT?
>>>
>>> Yes, that would be great.
>> I will need to update
>> https://svn.apache.org/viewvc/httpcomponents/maven-skin/trunk/
>>
>> Do you want to do it on Subversion, or do you prefer to switch to Git
>> first?
>>
>
> Yes, please. Switching it to Git would great.
I have raised the question about our skin some time ago. The concensus
was to drop it altogether and use Fluido at most with a few CSS
modifications.
Does my memory serve me well?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2021-02-02 at 08:32 +0100, Hervé BOUTEMY wrote:
> Le dimanche 31 janvier 2021, 10:03:44 CET Oleg Kalnichevski a écrit :
> > > One useful thing that we can do is adding "edit" icon like we
> > > have on
> > > the
> > > Maven website, the little icon in breadcrumb:
> > > https://maven.apache.org/
> > > This would ease finding the source file from a page, then edit
> > > easily
> > > in Github
> > > (eventually forking to create a PR). From Maven experience, it
> > > eases
> > > things a
> > > lot both for contributors (who don't know details), but even for
> > > seasoned
> > > developers, who know, but find it cumbersome to find the source.
> > > WDYT?
> >
> > Yes, that would be great.
> I will need to update
> https://svn.apache.org/viewvc/httpcomponents/maven-skin/trunk/
>
> Do you want to do it on Subversion, or do you prefer to switch to Git
> first?
>
Yes, please. Switching it to Git would great.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
Le dimanche 31 janvier 2021, 10:03:44 CET Oleg Kalnichevski a écrit :
> > One useful thing that we can do is adding "edit" icon like we have on
> > the
> > Maven website, the little icon in breadcrumb:
> > https://maven.apache.org/
> > This would ease finding the source file from a page, then edit easily
> > in Github
> > (eventually forking to create a PR). From Maven experience, it eases
> > things a
> > lot both for contributors (who don't know details), but even for
> > seasoned
> > developers, who know, but find it cumbersome to find the source.
> > WDYT?
>
> Yes, that would be great.
I will need to update
https://svn.apache.org/viewvc/httpcomponents/maven-skin/trunk/
Do you want to do it on Subversion, or do you prefer to switch to Git first?
>
> 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: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2021-01-30 at 22:23 +0100, Hervé BOUTEMY wrote:
> Le samedi 30 janvier 2021, 19:41:55 CET Oleg Kalnichevski a écrit :
> > On Sat, 2021-01-30 at 18:16 +0100, Hervé BOUTEMY wrote:
> > > Hi,
> > >
> > > As promised, here is an explanation of where we are and where we
> > > go
> > > next.
> >
> > Hi Hervé
> >
> > I think I now more or less understand the overall process. Thank
> > you
> > for your help and explanations.
> glad that you now see the overall scheme.
> I will remain with you all to finish details
>
> > If you still have some spare time and good will left to help us,
> > please
> > help us simplify the main project website by, for instance,
> > switching
> > it from APT to Markdown (or some other alternative discussed in the
> > past).
> I don't know yet magical solution for going from Apt to Markdown, but
> I
> suppose this is something many people are interested in: I'll see how
> we could
> create reusable helpers
>
> One useful thing that we can do is adding "edit" icon like we have on
> the
> Maven website, the little icon in breadcrumb:
> https://maven.apache.org/
> This would ease finding the source file from a page, then edit easily
> in Github
> (eventually forking to create a PR). From Maven experience, it eases
> things a
> lot both for contributors (who don't know details), but even for
> seasoned
> developers, who know, but find it cumbersome to find the source.
> WDYT?
>
Yes, that would be great.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
Le samedi 30 janvier 2021, 19:41:55 CET Oleg Kalnichevski a écrit :
> On Sat, 2021-01-30 at 18:16 +0100, Hervé BOUTEMY wrote:
> > Hi,
> >
> > As promised, here is an explanation of where we are and where we go
> > next.
>
> Hi Hervé
>
> I think I now more or less understand the overall process. Thank you
> for your help and explanations.
glad that you now see the overall scheme.
I will remain with you all to finish details
>
> If you still have some spare time and good will left to help us, please
> help us simplify the main project website by, for instance, switching
> it from APT to Markdown (or some other alternative discussed in the
> past).
I don't know yet magical solution for going from Apt to Markdown, but I
suppose this is something many people are interested in: I'll see how we could
create reusable helpers
One useful thing that we can do is adding "edit" icon like we have on the
Maven website, the little icon in breadcrumb:
https://maven.apache.org/
This would ease finding the source file from a page, then edit easily in Github
(eventually forking to create a PR). From Maven experience, it eases things a
lot both for contributors (who don't know details), but even for seasoned
developers, who know, but find it cumbersome to find the source.
WDYT?
>
> Oleg
>
> > HttpCore and HttpClient have been updated to publish their
> > documentation generated from source to:
> > http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST and
> > http://hc.apache.org/components/httpcomponents-client-5.0.x/LATEST
> >
> > At any time, during SNAPSHOT development or at release staging time,
> > documentation can be:
> > 1. generated from source code: mvn site site:stage
> > 2. then published to LATEST directory: mvn scm-publish:publish-scm
> > by any team member (once initial directory creation in svn will be ok
> > [1])
> >
> >
> > Integration of this documentation to the main site requires to merge
> > next PR:
> > https://github.com/apache/httpcomponents-website/pull/9
> > It will create symbolic links that will inject content in normal
> > website directories (without the "/components/" parts that seems
> > strange, explanation will follow...)
> >
> > When you'll do a release, the release manager will publish the
> > documentation and provide "LATEST" url, for review during the vote.
> > Once the vote will be ok, the state of the staging documentation will
> > have to be marked as a release: this will be done with a "svn cp"
> > command, like shown in the website PR [2]
> >
> >
> > Why this components/ directory?
> > The html website consists of the main website "unversioned" content
> > and the documentation generated from source (LATEST and every release
> > that the project will want to keep online).
> > If you build unversioned website and look at "target/site", you'll
> > see that the content is 1,112 kB for 75 files.
> > But if you look at the content in svn [3], there are currently 51,740
> > files for 1,071,288 kB: there is documentation for each component
> > branch, and that documentation will grow in the future with LATEST
> > and every release
> > Then the website publication job on Jankins [4] will in the future
> > svn checkout more and more content to update only these 75 files that
> > are the unversioned content.
> >
> > Separating documentation in a separate directory of the site is a
> > first step to fix this scalability issue: in a second step, we'll
> > move this svn directory to a location that is fully separate, then
> > won't be checked out by website publication job.
> >
> >
> > I hope this explanation helps everybody understand how release
> > documentation will be published easily and kept as much as you need.
> >
> > Regards,
> >
> > Hervé
> >
> >
> > [1] https://github.com/apache/httpcomponents-client/pull/280
> >
> > [2]
> > https://github.com/apache/httpcomponents-website/pull/9/files#diff-750296d
> > b9b9b33a71f10fa5eda497d2aabe583aad8be1b87a5ea2bb89957bcdf
> >
> > [3] https://svn.apache.org/repos/asf/httpcomponents/site/
> > https://svn.apache.org/viewvc/httpcomponents/site/
> >
> > [4]
> > https://ci-builds.apache.org/job/HttpComponents/job/HttpComponents%20Websi
> > te/
> >
> >
> >
> > ---------------------------------------------------------------------
> > 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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2021-01-30 at 18:16 +0100, Hervé BOUTEMY wrote:
> Hi,
>
> As promised, here is an explanation of where we are and where we go
> next.
>
Hi Hervé
I think I now more or less understand the overall process. Thank you
for your help and explanations.
If you still have some spare time and good will left to help us, please
help us simplify the main project website by, for instance, switching
it from APT to Markdown (or some other alternative discussed in the
past).
Oleg
> HttpCore and HttpClient have been updated to publish their
> documentation generated from source to:
> http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST and
> http://hc.apache.org/components/httpcomponents-client-5.0.x/LATEST
>
> At any time, during SNAPSHOT development or at release staging time,
> documentation can be:
> 1. generated from source code: mvn site site:stage
> 2. then published to LATEST directory: mvn scm-publish:publish-scm
> by any team member (once initial directory creation in svn will be ok
> [1])
>
>
> Integration of this documentation to the main site requires to merge
> next PR:
> https://github.com/apache/httpcomponents-website/pull/9
> It will create symbolic links that will inject content in normal
> website directories (without the "/components/" parts that seems
> strange, explanation will follow...)
>
> When you'll do a release, the release manager will publish the
> documentation and provide "LATEST" url, for review during the vote.
> Once the vote will be ok, the state of the staging documentation will
> have to be marked as a release: this will be done with a "svn cp"
> command, like shown in the website PR [2]
>
>
> Why this components/ directory?
> The html website consists of the main website "unversioned" content
> and the documentation generated from source (LATEST and every release
> that the project will want to keep online).
> If you build unversioned website and look at "target/site", you'll
> see that the content is 1,112 kB for 75 files.
> But if you look at the content in svn [3], there are currently 51,740
> files for 1,071,288 kB: there is documentation for each component
> branch, and that documentation will grow in the future with LATEST
> and every release
> Then the website publication job on Jankins [4] will in the future
> svn checkout more and more content to update only these 75 files that
> are the unversioned content.
>
> Separating documentation in a separate directory of the site is a
> first step to fix this scalability issue: in a second step, we'll
> move this svn directory to a location that is fully separate, then
> won't be checked out by website publication job.
>
>
> I hope this explanation helps everybody understand how release
> documentation will be published easily and kept as much as you need.
>
> Regards,
>
> Hervé
>
>
> [1] https://github.com/apache/httpcomponents-client/pull/280
>
> [2]
> https://github.com/apache/httpcomponents-website/pull/9/files#diff-750296db9b9b33a71f10fa5eda497d2aabe583aad8be1b87a5ea2bb89957bcdf
>
> [3] https://svn.apache.org/repos/asf/httpcomponents/site/
> https://svn.apache.org/viewvc/httpcomponents/site/
>
> [4]
> https://ci-builds.apache.org/job/HttpComponents/job/HttpComponents%20Website/
>
>
>
> ---------------------------------------------------------------------
> 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: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
Le mardi 2 février 2021, 23:28:07 CET Oleg Kalnichevski a écrit :
> > > Thank you, Hervé. Fundamentally the plan is to have non-versioned
> > > (release series specific) content at
> > >
> > > httpcomponents-core-5.1.x/
> > >
> > > and versioned (version specific) content at
> > >
> > > httpcomponents-core-5.1.x/5.1-beta3
> > > httpcomponents-core-5.1.x/5.1.0
> > > httpcomponents-core-5.1.x/5.1.1
> > > httpcomponents-core-5.1.x/5.1.2
> > >
> > >
> > > Do I get it correctly?
> >
> > exactly
>
> What are the benefits? History? Fundamentally only the last patch
> release in the release series is of any practical use.
it's a choice: you can do as you wish, every option is easily feasible
>
> It might as well just be
>
> httpcomponents-core-5.1.x/LATEST
if you want, or you can name it "current", or "doc" as initially
Pure choice of the project, I won't interfere: no choice is wrong per-se
notice that you should not wait to merge
https://github.com/apache/httpcomponents-website/pull/9
because without the PR, any change to the website will delete "/components"
directory (as it is neither a result of the site build, nor configured to be
ignored = what the PR does)
>
> 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: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
Le vendredi 5 février 2021, 18:32:39 CET Oleg Kalnichevski a écrit :
> > and why is it Central rules for javadocs and sources?
> > because it is useful for IDEs lookup for every end-user (which
> > honestly
> > nowadays only require sources, not javadocs any more: Central rules
> > could
> > probably be lightened, but that's another story)
> > other reports are not useful for any normal end-user (through their
> > IDE or any
> > other tools): other reports are purely project internal details, to
> > publish to
> > project's website = what svnpubsub and its internal svn storage are
> > done for
>
> and why would not an API compatibility report to useful for every
> normal end-user? Why do no we publish those reports on our project
> website if they are not useful?
Yes, useful on your website for users using their web browsers to look at it
But not useful as a zip file pushed to Maven Central
Don't hesitate to test such a report for example with japicmp-maven-plugin
https://siom79.github.io/japicmp/
And publish the SNAPSHOT doc to LATEST
That's what the current structure makes easy.
>
> > I hope it can help build better mutual understanding
>
> I am fine agreeing to disagree here.
it seems mutual efforts are not mutual: ok, no problem, I was just helping, job
done, I can get back to use my time where it is enjoyable
>
> Anyways, website content management should be working now exactly as
> you have recommended.
the last point will be to move /components to a separate svn tree: @Michael, I
suppose you understand and know how to do that (and I can't do it for you,
require INFRA tasks)
>
> The last thing I would really appreciate you could help us do is
> migration from APT to Markdown.
sorry, I don't have any tools for that: it's a job to be done file by file, at
your own pace
bye
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: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Fri, 2021-02-05 at 08:36 +0100, Hervé BOUTEMY wrote:
> Le jeudi 4 février 2021, 19:14:03 CET Oleg Kalnichevski a écrit :
> > > Please note that one can push generated non-stable stuff to this
> > > while
> > > the stable will point to. I consider it logically. Since we are
> > > tagging
> > > our source code and finalize its produced binaries in Maven
> > > Central,
> > > so
> > > should this apply to any other generated content.
> >
> > This is precisely why versioned reports should also go into Maven
> > Central. That is what we do with javadocs and sources.
> just FYI:
>
> javadocs and sources go to Central because it's Central rules to
> require them:
> other reports are not part of these rules
>
> and why is it Central rules for javadocs and sources?
> because it is useful for IDEs lookup for every end-user (which
> honestly
> nowadays only require sources, not javadocs any more: Central rules
> could
> probably be lightened, but that's another story)
> other reports are not useful for any normal end-user (through their
> IDE or any
> other tools): other reports are purely project internal details, to
> publish to
> project's website = what svnpubsub and its internal svn storage are
> done for
>
and why would not an API compatibility report to useful for every
normal end-user? Why do no we publish those reports on our project
website if they are not useful?
> I hope it can help build better mutual understanding
>
I am fine agreeing to disagree here.
Anyways, website content management should be working now exactly as
you have recommended.
The last thing I would really appreciate you could help us do is
migration from APT to Markdown.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
Le jeudi 4 février 2021, 19:14:03 CET Oleg Kalnichevski a écrit :
> > Please note that one can push generated non-stable stuff to this
> > while
> > the stable will point to. I consider it logically. Since we are
> > tagging
> > our source code and finalize its produced binaries in Maven Central,
> > so
> > should this apply to any other generated content.
>
> This is precisely why versioned reports should also go into Maven
> Central. That is what we do with javadocs and sources.
just FYI:
javadocs and sources go to Central because it's Central rules to require them:
other reports are not part of these rules
and why is it Central rules for javadocs and sources?
because it is useful for IDEs lookup for every end-user (which honestly
nowadays only require sources, not javadocs any more: Central rules could
probably be lightened, but that's another story)
other reports are not useful for any normal end-user (through their IDE or any
other tools): other reports are purely project internal details, to publish to
project's website = what svnpubsub and its internal svn storage are done for
I hope it can help build better mutual understanding
>
> 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: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Thu, 2021-02-04 at 17:41 +0100, Michael Osipov wrote:
> Am 2021-02-02 um 23:28 schrieb Oleg Kalnichevski:
> > On Tue, 2021-02-02 at 23:21 +0100, Hervé BOUTEMY wrote:
> > > Le mardi 2 février 2021, 22:57:40 CET Oleg Kalnichevski a écrit :
> > > > On Tue, 2021-02-02 at 22:40 +0100, Hervé BOUTEMY wrote:
> > > > > Le mardi 2 février 2021, 21:08:52 CET Oleg Kalnichevski a
> > > > > écrit :
> > > > > > On Tue, 2021-02-02 at 08:30 +0100, Hervé BOUTEMY wrote:
> > > > > > > Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a
> > > > > > > écrit
> > > > > > > :
> > > > > > > > Hi Hervé,
> > > > > > > >
> > > > > > > > Thank you for your hard work on this!
> > > > > > > >
> > > > > > > > Are these two "LATEST" URLs supposed to be up?
> > > > > > >
> > > > > > > if someone from the team (with commit access) wants to
> > > > > > > execute
> > > > > > > the
> > > > > > > publication
> > > > > > > (and do the manual init step to create base svn
> > > > > > > directory):
> > > > > > > https://github.com/apache/httpcomponents-client/pull/280
> > > > > >
> > > > > > Hi Hervé
> > > > > >
> > > > > > I published HttpCore 5.1-beta3 content generated with Maven
> > > > > > Site to
> > > > > > as
> > > > > > per your instructions:
> > > > > >
> > > > > > http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST/
> > > > > >
> > > > > > Most of it looks pretty useless to me except for Javadocs
> > > > > > and
> > > > > > Clirr
> > > > > > reports.
> > > > > >
> > > > > > I am not quite sure how you propose we should make use of
> > > > > > that
> > > > > > content.
> > > > > >
> > > > > > Shall we just link the reports from the main project
> > > > > > website
> > > > > > and
> > > > > > let
> > > > > > the rest be?
> > > > >
> > > > > yes, exactly, no revolution
> > > > >
> > > > > Regards,
> > > > >
> > > > > Hervé
> > > >
> > > > Thank you, Hervé. Fundamentally the plan is to have non-
> > > > versioned
> > > > (release series specific) content at
> > > >
> > > > httpcomponents-core-5.1.x/
> > > >
> > > > and versioned (version specific) content at
> > > >
> > > > httpcomponents-core-5.1.x/5.1-beta3
> > > > httpcomponents-core-5.1.x/5.1.0
> > > > httpcomponents-core-5.1.x/5.1.1
> > > > httpcomponents-core-5.1.x/5.1.2
> > > >
> > > >
> > > > Do I get it correctly?
> > > exactly
> > >
> >
> > What are the benefits? History? Fundamentally only the last patch
> > release in the release series is of any practical use.
>
> Traceability and branches are cheap with Subversion. It only stores
> the
> delta.
>
> > It might as well just be
> >
> > httpcomponents-core-5.1.x/LATEST
>
> Please note that one can push generated non-stable stuff to this
> while
> the stable will point to. I consider it logically. Since we are
> tagging
> our source code and finalize its produced binaries in Maven Central,
> so
> should this apply to any other generated content.
This is precisely why versioned reports should also go into Maven
Central. That is what we do with javadocs and sources.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Michael Osipov <mi...@apache.org>.
Am 2021-02-02 um 23:28 schrieb Oleg Kalnichevski:
> On Tue, 2021-02-02 at 23:21 +0100, Hervé BOUTEMY wrote:
>> Le mardi 2 février 2021, 22:57:40 CET Oleg Kalnichevski a écrit :
>>> On Tue, 2021-02-02 at 22:40 +0100, Hervé BOUTEMY wrote:
>>>> Le mardi 2 février 2021, 21:08:52 CET Oleg Kalnichevski a écrit :
>>>>> On Tue, 2021-02-02 at 08:30 +0100, Hervé BOUTEMY wrote:
>>>>>> Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a écrit
>>>>>> :
>>>>>>> Hi Hervé,
>>>>>>>
>>>>>>> Thank you for your hard work on this!
>>>>>>>
>>>>>>> Are these two "LATEST" URLs supposed to be up?
>>>>>>
>>>>>> if someone from the team (with commit access) wants to
>>>>>> execute
>>>>>> the
>>>>>> publication
>>>>>> (and do the manual init step to create base svn directory):
>>>>>> https://github.com/apache/httpcomponents-client/pull/280
>>>>>
>>>>> Hi Hervé
>>>>>
>>>>> I published HttpCore 5.1-beta3 content generated with Maven
>>>>> Site to
>>>>> as
>>>>> per your instructions:
>>>>>
>>>>> http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST/
>>>>>
>>>>> Most of it looks pretty useless to me except for Javadocs and
>>>>> Clirr
>>>>> reports.
>>>>>
>>>>> I am not quite sure how you propose we should make use of that
>>>>> content.
>>>>>
>>>>> Shall we just link the reports from the main project website
>>>>> and
>>>>> let
>>>>> the rest be?
>>>>
>>>> yes, exactly, no revolution
>>>>
>>>> Regards,
>>>>
>>>> Hervé
>>>
>>> Thank you, Hervé. Fundamentally the plan is to have non-versioned
>>> (release series specific) content at
>>>
>>> httpcomponents-core-5.1.x/
>>>
>>> and versioned (version specific) content at
>>>
>>> httpcomponents-core-5.1.x/5.1-beta3
>>> httpcomponents-core-5.1.x/5.1.0
>>> httpcomponents-core-5.1.x/5.1.1
>>> httpcomponents-core-5.1.x/5.1.2
>>>
>>>
>>> Do I get it correctly?
>> exactly
>>
>
> What are the benefits? History? Fundamentally only the last patch
> release in the release series is of any practical use.
Traceability and branches are cheap with Subversion. It only stores the
delta.
> It might as well just be
>
> httpcomponents-core-5.1.x/LATEST
Please note that one can push generated non-stable stuff to this while
the stable will point to. I consider it logically. Since we are tagging
our source code and finalize its produced binaries in Maven Central, so
should this apply to any other generated content. This especially
applies to content which lives in those in src/site/{markdown,apt/asciidoc}.
M
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2021-02-02 at 23:21 +0100, Hervé BOUTEMY wrote:
> Le mardi 2 février 2021, 22:57:40 CET Oleg Kalnichevski a écrit :
> > On Tue, 2021-02-02 at 22:40 +0100, Hervé BOUTEMY wrote:
> > > Le mardi 2 février 2021, 21:08:52 CET Oleg Kalnichevski a écrit :
> > > > On Tue, 2021-02-02 at 08:30 +0100, Hervé BOUTEMY wrote:
> > > > > Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a écrit
> > > > > :
> > > > > > Hi Hervé,
> > > > > >
> > > > > > Thank you for your hard work on this!
> > > > > >
> > > > > > Are these two "LATEST" URLs supposed to be up?
> > > > >
> > > > > if someone from the team (with commit access) wants to
> > > > > execute
> > > > > the
> > > > > publication
> > > > > (and do the manual init step to create base svn directory):
> > > > > https://github.com/apache/httpcomponents-client/pull/280
> > > >
> > > > Hi Hervé
> > > >
> > > > I published HttpCore 5.1-beta3 content generated with Maven
> > > > Site to
> > > > as
> > > > per your instructions:
> > > >
> > > > http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST/
> > > >
> > > > Most of it looks pretty useless to me except for Javadocs and
> > > > Clirr
> > > > reports.
> > > >
> > > > I am not quite sure how you propose we should make use of that
> > > > content.
> > > >
> > > > Shall we just link the reports from the main project website
> > > > and
> > > > let
> > > > the rest be?
> > >
> > > yes, exactly, no revolution
> > >
> > > Regards,
> > >
> > > Hervé
> >
> > Thank you, Hervé. Fundamentally the plan is to have non-versioned
> > (release series specific) content at
> >
> > httpcomponents-core-5.1.x/
> >
> > and versioned (version specific) content at
> >
> > httpcomponents-core-5.1.x/5.1-beta3
> > httpcomponents-core-5.1.x/5.1.0
> > httpcomponents-core-5.1.x/5.1.1
> > httpcomponents-core-5.1.x/5.1.2
> >
> >
> > Do I get it correctly?
> exactly
>
What are the benefits? History? Fundamentally only the last patch
release in the release series is of any practical use.
It might as well just be
httpcomponents-core-5.1.x/LATEST
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
Le mardi 2 février 2021, 22:57:40 CET Oleg Kalnichevski a écrit :
> On Tue, 2021-02-02 at 22:40 +0100, Hervé BOUTEMY wrote:
> > Le mardi 2 février 2021, 21:08:52 CET Oleg Kalnichevski a écrit :
> > > On Tue, 2021-02-02 at 08:30 +0100, Hervé BOUTEMY wrote:
> > > > Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a écrit :
> > > > > Hi Hervé,
> > > > >
> > > > > Thank you for your hard work on this!
> > > > >
> > > > > Are these two "LATEST" URLs supposed to be up?
> > > >
> > > > if someone from the team (with commit access) wants to execute
> > > > the
> > > > publication
> > > > (and do the manual init step to create base svn directory):
> > > > https://github.com/apache/httpcomponents-client/pull/280
> > >
> > > Hi Hervé
> > >
> > > I published HttpCore 5.1-beta3 content generated with Maven Site to
> > > as
> > > per your instructions:
> > >
> > > http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST/
> > >
> > > Most of it looks pretty useless to me except for Javadocs and Clirr
> > > reports.
> > >
> > > I am not quite sure how you propose we should make use of that
> > > content.
> > >
> > > Shall we just link the reports from the main project website and
> > > let
> > > the rest be?
> >
> > yes, exactly, no revolution
> >
> > Regards,
> >
> > Hervé
>
> Thank you, Hervé. Fundamentally the plan is to have non-versioned
> (release series specific) content at
>
> httpcomponents-core-5.1.x/
>
> and versioned (version specific) content at
>
> httpcomponents-core-5.1.x/5.1-beta3
> httpcomponents-core-5.1.x/5.1.0
> httpcomponents-core-5.1.x/5.1.1
> httpcomponents-core-5.1.x/5.1.2
>
>
> Do I get it correctly?
exactly
>
> 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: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2021-02-02 at 22:40 +0100, Hervé BOUTEMY wrote:
> Le mardi 2 février 2021, 21:08:52 CET Oleg Kalnichevski a écrit :
> > On Tue, 2021-02-02 at 08:30 +0100, Hervé BOUTEMY wrote:
> > > Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a écrit :
> > > > Hi Hervé,
> > > >
> > > > Thank you for your hard work on this!
> > > >
> > > > Are these two "LATEST" URLs supposed to be up?
> > >
> > > if someone from the team (with commit access) wants to execute
> > > the
> > > publication
> > > (and do the manual init step to create base svn directory):
> > > https://github.com/apache/httpcomponents-client/pull/280
> >
> > Hi Hervé
> >
> > I published HttpCore 5.1-beta3 content generated with Maven Site to
> > as
> > per your instructions:
> >
> > http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST/
> >
> > Most of it looks pretty useless to me except for Javadocs and Clirr
> > reports.
> >
> > I am not quite sure how you propose we should make use of that
> > content.
> >
> > Shall we just link the reports from the main project website and
> > let
> > the rest be?
> yes, exactly, no revolution
>
> Regards,
>
> Hervé
>
Thank you, Hervé. Fundamentally the plan is to have non-versioned
(release series specific) content at
httpcomponents-core-5.1.x/
and versioned (version specific) content at
httpcomponents-core-5.1.x/5.1-beta3
httpcomponents-core-5.1.x/5.1.0
httpcomponents-core-5.1.x/5.1.1
httpcomponents-core-5.1.x/5.1.2
Do I get it correctly?
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
Le mardi 2 février 2021, 21:08:52 CET Oleg Kalnichevski a écrit :
> On Tue, 2021-02-02 at 08:30 +0100, Hervé BOUTEMY wrote:
> > Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a écrit :
> > > Hi Hervé,
> > >
> > > Thank you for your hard work on this!
> > >
> > > Are these two "LATEST" URLs supposed to be up?
> >
> > if someone from the team (with commit access) wants to execute the
> > publication
> > (and do the manual init step to create base svn directory):
> > https://github.com/apache/httpcomponents-client/pull/280
>
> Hi Hervé
>
> I published HttpCore 5.1-beta3 content generated with Maven Site to as
> per your instructions:
>
> http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST/
>
> Most of it looks pretty useless to me except for Javadocs and Clirr
> reports.
>
> I am not quite sure how you propose we should make use of that content.
>
> Shall we just link the reports from the main project website and let
> the rest be?
yes, exactly, no revolution
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: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2021-02-02 at 08:30 +0100, Hervé BOUTEMY wrote:
> Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a écrit :
> > Hi Hervé,
> >
> > Thank you for your hard work on this!
> >
> > Are these two "LATEST" URLs supposed to be up?
> if someone from the team (with commit access) wants to execute the
> publication
> (and do the manual init step to create base svn directory):
> https://github.com/apache/httpcomponents-client/pull/280
>
Hi Hervé
I published HttpCore 5.1-beta3 content generated with Maven Site to as
per your instructions:
http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST/
Most of it looks pretty useless to me except for Javadocs and Clirr
reports.
I am not quite sure how you propose we should make use of that content.
Shall we just link the reports from the main project website and let
the rest be?
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2021-02-02 at 08:30 +0100, Hervé BOUTEMY wrote:
> Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a écrit :
> > Hi Hervé,
> >
> > Thank you for your hard work on this!
> >
> > Are these two "LATEST" URLs supposed to be up?
> if someone from the team (with commit access) wants to execute the
> publication
> (and do the manual init step to create base svn directory):
> https://github.com/apache/httpcomponents-client/pull/280
>
It will publish the content as soon as HttpCore 5.1-beta3 release is
complete.
Oleg
> > Gary
> >
> > On Sat, Jan 30, 2021, 12:16 Hervé BOUTEMY <he...@free.fr>
> > wrote:
> > > Hi,
> > >
> > > As promised, here is an explanation of where we are and where we
> > > go next.
> > >
> > > HttpCore and HttpClient have been updated to publish their
> > > documentation
> > > generated from source to:
> > > http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST
> > > and
> > > http://hc.apache.org/components/httpcomponents-client-5.0.x/LATEST
> > >
> > > At any time, during SNAPSHOT development or at release staging
> > > time,
> > > documentation can be:
> > > 1. generated from source code: mvn site site:stage
> > > 2. then published to LATEST directory: mvn scm-publish:publish-
> > > scm
> > > by any team member (once initial directory creation in svn will
> > > be ok [1])
> > >
> > >
> > > Integration of this documentation to the main site requires to
> > > merge next
> > > PR:
> > > https://github.com/apache/httpcomponents-website/pull/9
> > > It will create symbolic links that will inject content in normal
> > > website
> > > directories (without the "/components/" parts that seems strange,
> > > explanation will follow...)
> > >
> > > When you'll do a release, the release manager will publish the
> > > documentation and provide "LATEST" url, for review during the
> > > vote.
> > > Once the vote will be ok, the state of the staging documentation
> > > will have
> > > to be marked as a release: this will be done with a "svn cp"
> > > command, like
> > > shown in the website PR [2]
> > >
> > >
> > > Why this components/ directory?
> > > The html website consists of the main website "unversioned"
> > > content and
> > > the documentation generated from source (LATEST and every release
> > > that the
> > > project will want to keep online).
> > > If you build unversioned website and look at "target/site",
> > > you'll see
> > > that the content is 1,112 kB for 75 files.
> > > But if you look at the content in svn [3], there are currently
> > > 51,740
> > > files for 1,071,288 kB: there is documentation for each component
> > > branch,
> > > and that documentation will grow in the future with LATEST and
> > > every
> > > release Then the website publication job on Jankins [4] will in
> > > the
> > > future svn checkout more and more content to update only these 75
> > > files
> > > that are the unversioned content.
> > >
> > > Separating documentation in a separate directory of the site is a
> > > first
> > > step to fix this scalability issue: in a second step, we'll move
> > > this svn
> > > directory to a location that is fully separate, then won't be
> > > checked out
> > > by website publication job.
> > >
> > >
> > > I hope this explanation helps everybody understand how release
> > > documentation will be published easily and kept as much as you
> > > need.
> > >
> > > Regards,
> > >
> > > Hervé
> > >
> > >
> > > [1] https://github.com/apache/httpcomponents-client/pull/280
> > >
> > > [2]
> > > https://github.com/apache/httpcomponents-website/pull/9/files#diff-750296d
> > > b9b9b33a71f10fa5eda497d2aabe583aad8be1b87a5ea2bb89957bcdf
> > >
> > > [3] https://svn.apache.org/repos/asf/httpcomponents/site/
> > > https://svn.apache.org/viewvc/httpcomponents/site/
> > >
> > > [4]
> > > https://ci-builds.apache.org/job/HttpComponents/job/HttpComponents%20Websi
> > > te/
> > >
> > >
> > >
> > > ---------------------------------------------------------------
> > > ------
> > > 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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: website + releases documentation publication structure
Posted by Hervé BOUTEMY <he...@free.fr>.
Le samedi 30 janvier 2021, 18:32:35 CET Gary Gregory a écrit :
> Hi Hervé,
>
> Thank you for your hard work on this!
>
> Are these two "LATEST" URLs supposed to be up?
if someone from the team (with commit access) wants to execute the publication
(and do the manual init step to create base svn directory):
https://github.com/apache/httpcomponents-client/pull/280
>
> Gary
>
> On Sat, Jan 30, 2021, 12:16 Hervé BOUTEMY <he...@free.fr> wrote:
> > Hi,
> >
> > As promised, here is an explanation of where we are and where we go next.
> >
> > HttpCore and HttpClient have been updated to publish their documentation
> > generated from source to:
> > http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST and
> > http://hc.apache.org/components/httpcomponents-client-5.0.x/LATEST
> >
> > At any time, during SNAPSHOT development or at release staging time,
> > documentation can be:
> > 1. generated from source code: mvn site site:stage
> > 2. then published to LATEST directory: mvn scm-publish:publish-scm
> > by any team member (once initial directory creation in svn will be ok [1])
> >
> >
> > Integration of this documentation to the main site requires to merge next
> > PR:
> > https://github.com/apache/httpcomponents-website/pull/9
> > It will create symbolic links that will inject content in normal website
> > directories (without the "/components/" parts that seems strange,
> > explanation will follow...)
> >
> > When you'll do a release, the release manager will publish the
> > documentation and provide "LATEST" url, for review during the vote.
> > Once the vote will be ok, the state of the staging documentation will have
> > to be marked as a release: this will be done with a "svn cp" command, like
> > shown in the website PR [2]
> >
> >
> > Why this components/ directory?
> > The html website consists of the main website "unversioned" content and
> > the documentation generated from source (LATEST and every release that the
> > project will want to keep online).
> > If you build unversioned website and look at "target/site", you'll see
> > that the content is 1,112 kB for 75 files.
> > But if you look at the content in svn [3], there are currently 51,740
> > files for 1,071,288 kB: there is documentation for each component branch,
> > and that documentation will grow in the future with LATEST and every
> > release Then the website publication job on Jankins [4] will in the
> > future svn checkout more and more content to update only these 75 files
> > that are the unversioned content.
> >
> > Separating documentation in a separate directory of the site is a first
> > step to fix this scalability issue: in a second step, we'll move this svn
> > directory to a location that is fully separate, then won't be checked out
> > by website publication job.
> >
> >
> > I hope this explanation helps everybody understand how release
> > documentation will be published easily and kept as much as you need.
> >
> > Regards,
> >
> > Hervé
> >
> >
> > [1] https://github.com/apache/httpcomponents-client/pull/280
> >
> > [2]
> > https://github.com/apache/httpcomponents-website/pull/9/files#diff-750296d
> > b9b9b33a71f10fa5eda497d2aabe583aad8be1b87a5ea2bb89957bcdf
> >
> > [3] https://svn.apache.org/repos/asf/httpcomponents/site/
> > https://svn.apache.org/viewvc/httpcomponents/site/
> >
> > [4]
> > https://ci-builds.apache.org/job/HttpComponents/job/HttpComponents%20Websi
> > te/
> >
> >
> >
> > ---------------------------------------------------------------------
> > 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: website + releases documentation publication structure
Posted by Gary Gregory <ga...@gmail.com>.
Hi Hervé,
Thank you for your hard work on this!
Are these two "LATEST" URLs supposed to be up?
Gary
On Sat, Jan 30, 2021, 12:16 Hervé BOUTEMY <he...@free.fr> wrote:
> Hi,
>
> As promised, here is an explanation of where we are and where we go next.
>
> HttpCore and HttpClient have been updated to publish their documentation
> generated from source to:
> http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST and
> http://hc.apache.org/components/httpcomponents-client-5.0.x/LATEST
>
> At any time, during SNAPSHOT development or at release staging time,
> documentation can be:
> 1. generated from source code: mvn site site:stage
> 2. then published to LATEST directory: mvn scm-publish:publish-scm
> by any team member (once initial directory creation in svn will be ok [1])
>
>
> Integration of this documentation to the main site requires to merge next
> PR:
> https://github.com/apache/httpcomponents-website/pull/9
> It will create symbolic links that will inject content in normal website
> directories (without the "/components/" parts that seems strange,
> explanation will follow...)
>
> When you'll do a release, the release manager will publish the
> documentation and provide "LATEST" url, for review during the vote.
> Once the vote will be ok, the state of the staging documentation will have
> to be marked as a release: this will be done with a "svn cp" command, like
> shown in the website PR [2]
>
>
> Why this components/ directory?
> The html website consists of the main website "unversioned" content and
> the documentation generated from source (LATEST and every release that the
> project will want to keep online).
> If you build unversioned website and look at "target/site", you'll see
> that the content is 1,112 kB for 75 files.
> But if you look at the content in svn [3], there are currently 51,740
> files for 1,071,288 kB: there is documentation for each component branch,
> and that documentation will grow in the future with LATEST and every release
> Then the website publication job on Jankins [4] will in the future svn
> checkout more and more content to update only these 75 files that are the
> unversioned content.
>
> Separating documentation in a separate directory of the site is a first
> step to fix this scalability issue: in a second step, we'll move this svn
> directory to a location that is fully separate, then won't be checked out
> by website publication job.
>
>
> I hope this explanation helps everybody understand how release
> documentation will be published easily and kept as much as you need.
>
> Regards,
>
> Hervé
>
>
> [1] https://github.com/apache/httpcomponents-client/pull/280
>
> [2]
> https://github.com/apache/httpcomponents-website/pull/9/files#diff-750296db9b9b33a71f10fa5eda497d2aabe583aad8be1b87a5ea2bb89957bcdf
>
> [3] https://svn.apache.org/repos/asf/httpcomponents/site/
> https://svn.apache.org/viewvc/httpcomponents/site/
>
> [4]
> https://ci-builds.apache.org/job/HttpComponents/job/HttpComponents%20Website/
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
>
Re: Release management and project website management going
forward; was Re: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Mon, 2021-02-01 at 11:55 +0100, Michael Osipov wrote:
> Am 2021-01-30 um 19:51 schrieb Oleg Kalnichevski:
> > Folks
> >
> > I see three possible ways forward
> >
> > 2. I continue acting as a RM but my responsibilities end once I
> > have
> > delivered release content to
> > http://hc.apache.org/components/httpcomponents-xxx-xxx. Someone
> > else
> > steps in and completely takes over the project website management
> > including release updates and release announcements.
>
> Let's clarify this point please. At which point do you want to stop
> here?
> You will run "mvn site:stage && mvn scm-publish:publish-scm", but
> not
> after auccess vote copy from LATEST to XXX with svn(1)?
>
> M
>
After a successful release vote I will upload the content generated
with `mvn site:stage` either with `mvn scm-publish:publish-scm` or a
custom script.
The website content itself is NOT subject to the release vote.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Release management and project website management going forward;
was Re: website + releases documentation publication structure
Posted by Michael Osipov <mi...@apache.org>.
Am 2021-01-30 um 19:51 schrieb Oleg Kalnichevski:
> Folks
>
> I see three possible ways forward
>
> 2. I continue acting as a RM but my responsibilities end once I have
> delivered release content to
> http://hc.apache.org/components/httpcomponents-xxx-xxx. Someone else
> steps in and completely takes over the project website management
> including release updates and release announcements.
Let's clarify this point please. At which point do you want to stop here?
You will run "mvn site:stage && mvn scm-publish:publish-scm", but not
after auccess vote copy from LATEST to XXX with svn(1)?
M
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Release management and project website management going forward;
was Re: website + releases documentation publication structure
Posted by Oleg Kalnichevski <ol...@apache.org>.
Folks
I see three possible ways forward
1. Someone steps in and takes over the responsibility of a RM for all
or at least some development branches (4.x, 5.0.x, master). They can
adopt whatever release tools and methodology they are comfortable with.
2. I continue acting as a RM but my responsibilities end once I have
delivered release content to
http://hc.apache.org/components/httpcomponents-xxx-xxx. Someone else
steps in and completely takes over the project website management
including release updates and release announcements.
3. Everything stays as it is but in this case I should be entitled to
exploring other ways of managing our project website I feel more
comfortable with.
Cheers
Oleg
On Sat, 2021-01-30 at 18:16 +0100, Hervé BOUTEMY wrote:
> Hi,
>
> As promised, here is an explanation of where we are and where we go
> next.
>
> HttpCore and HttpClient have been updated to publish their
> documentation generated from source to:
> http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST and
> http://hc.apache.org/components/httpcomponents-client-5.0.x/LATEST
>
> At any time, during SNAPSHOT development or at release staging time,
> documentation can be:
> 1. generated from source code: mvn site site:stage
> 2. then published to LATEST directory: mvn scm-publish:publish-scm
> by any team member (once initial directory creation in svn will be ok
> [1])
>
>
> Integration of this documentation to the main site requires to merge
> next PR:
> https://github.com/apache/httpcomponents-website/pull/9
> It will create symbolic links that will inject content in normal
> website directories (without the "/components/" parts that seems
> strange, explanation will follow...)
>
> When you'll do a release, the release manager will publish the
> documentation and provide "LATEST" url, for review during the vote.
> Once the vote will be ok, the state of the staging documentation will
> have to be marked as a release: this will be done with a "svn cp"
> command, like shown in the website PR [2]
>
>
> Why this components/ directory?
> The html website consists of the main website "unversioned" content
> and the documentation generated from source (LATEST and every release
> that the project will want to keep online).
> If you build unversioned website and look at "target/site", you'll
> see that the content is 1,112 kB for 75 files.
> But if you look at the content in svn [3], there are currently 51,740
> files for 1,071,288 kB: there is documentation for each component
> branch, and that documentation will grow in the future with LATEST
> and every release
> Then the website publication job on Jankins [4] will in the future
> svn checkout more and more content to update only these 75 files that
> are the unversioned content.
>
> Separating documentation in a separate directory of the site is a
> first step to fix this scalability issue: in a second step, we'll
> move this svn directory to a location that is fully separate, then
> won't be checked out by website publication job.
>
>
> I hope this explanation helps everybody understand how release
> documentation will be published easily and kept as much as you need.
>
> Regards,
>
> Hervé
>
>
> [1] https://github.com/apache/httpcomponents-client/pull/280
>
> [2]
> https://github.com/apache/httpcomponents-website/pull/9/files#diff-750296db9b9b33a71f10fa5eda497d2aabe583aad8be1b87a5ea2bb89957bcdf
>
> [3] https://svn.apache.org/repos/asf/httpcomponents/site/
> https://svn.apache.org/viewvc/httpcomponents/site/
>
> [4]
> https://ci-builds.apache.org/job/HttpComponents/job/HttpComponents%20Website/
>
>
>
> ---------------------------------------------------------------------
> 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