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/02/02 07:30:11 UTC

Re: website + releases documentation publication structure

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 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