On 29 April 2018 at 09:41, Hervé BOUTEMY <herve.bout...@free.fr> wrote: > first, I want to reassure everybody: this is a discussion, to get common > knowledge of how things work in other projects then may work in the future > for Attic if we decide to do an equivalent setup
+1 > Le dimanche 29 avril 2018, 07:50:21 CEST sebb a écrit : >> On 28 April 2018 at 12:48, sebb <seb...@gmail.com> wrote: >> > On 28 April 2018 at 12:37, Hervé BOUTEMY <herve.bout...@free.fr> wrote: >> ... >> >> >> In Git, this would naturally be in a separate branch named "asf-site" >> >> How would that work for Attic? >> >> Where would the source files used to generate the site be held? > > There are multiple ways of doing, and GitHub documented it as clearly as > possible [2] > (yes, what we do at ASF with GitPubSub is exactly what GitHub calls "GitHub > Pages", with marketing bells turned on and technical details on the build > solution turned off) > > The 2 common ways are: > 1. publish html from separate branch (which would be by default "asf-site" at > ASF, and is "gh-pages" at GitHub) > 2. publish html from a subdirectory on master branch (you see Attic current > pattern?) > > I find the first option a lot more clear from a build+scm perspective than > the second one. > This will avoid the exact same discussion we have currently at Attic with svn > to know who commits the generated content (& when as a consequence): > - CI after source-only commit? > - or user who builds on his machine then commits simultaneously source and > generated content? > > Then looking at ASF gitwcsub configuration [2], I had a look at many ASF > projects: the 2 ways are used. > I picked Cayenne [3] case to show a case where: > - master branch is a source branch, with markup and a build script > - asf-site branch is a completely separate branch that contains generated html > It uses Maven scm-publish plugin to update asf-git branch with generated html > [6] > > But there is also Freemarker [4], that has a simple README telling "To > publish the built site, commit the output into the "asf-site" branch". > > Or Accumulo [5] which uses Jekyll and has some instructions to publish > generated output to asf-site branch with a git-hook that I don't fully > understand, but that maybe Attic members will prefer since it seems it's more > the common culture here > > Notice: I'm a Maven guy, I co-wrote the Maven scm-publish plugin used by > Cayenne, and I use it in many projects, initially with svn as target source > control (in 2012, for svnpubsub & Apache CMS) then with git also, when GitHub > pages became popular. > But I see that it's not the right choice at Attic because it's not the most > common Attic culture. Attic does not produce source code. The only output from its SCM is the website. AFAICT, all the above examples have a branch which contains the source for building the website. 1) The source is edited. 2) Run the build script to create the output in a clean subdirectory 3) Copy the subdirectory tree to the asf-site branch 4) commit the asf-site branch 5) The entire asf-site branch is then published via pubsub. What Attic does currently is: 1) & 2) as above 3) commit the changes 5) as above i.e. there is no need to copy the generated output anywhere because it is part of the same repo. This works because svnpubsub is set up to get its source from the docs/ subdirectory I don't know if gitpubsub can take its input from a subdirectory of a branch. If not, then we will have to change strategy in order to use Git. Otherwise, we have a choice. > Regards, > > Hervé > > > [1] > https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ > > [2] > https://github.com/apache/infrastructure-puppet/blob/deployment/modules/gitwcsub/files/config/gitwcsub.cfg > > [3] https://github.com/apache/cayenne-website/ > > [4] https://github.com/apache/freemarker-site > > [5] https://github.com/apache/accumulo-website > > [6] > https://maven.apache.org/plugins/maven-scm-publish-plugin/various-tips.html#Git_branch >
