Le dimanche 29 avril 2018, 11:04:44 CEST sebb a écrit : > 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. yes, like any other website that I showed: source code here is a markup language (be it Markdown, xdoc, static content, or anything else) Attic is really exactly the same
What makes Attic different is that Attic does not have any other repo for "programming" code: that's true, but does not change anything regarding site > > AFAICT, all the above examples have a branch which contains the source > for building the website. yes, I explained I chose them exactly for that reason I can show you Airavata site, which is quite simple and did the other choice: https://github.com/apache/airavata-site source is in source, output is in content in the same branch it could have been: source in master branch, content in asf-site branch which is the most common setup in GitHub pages (= what people nowadays know a lot) > > 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 yes, the setup with source and output in the same svn repo or Git branch makes it simple to checkout, but it mixes 2 types of files (source and generated) separating source and generated in 2 separate locations (separate svn root or different branches in the same git repo) makes things more clear, at the cost of an extra step to check out the generated content then update with the updated content yes: choose your issue personally, I prefer the second setup (clear but a little harder to setup) I don't like having mixed content in one repo (source and generated output) If everybody understands that these 2 setups a completely equivalent but really prefer the mixed one (just to avoid a second checkout), I'll let you go: I don't have any problem myself, I make a strong difference between source directory and output directory But if people start to edit output directory instead of source (like it is so easy to do in the mixed content setup), you're at risk > > I don't know if gitpubsub can take its input from a subdirectory of a > branch. it can: see Airavata site > If not, then we will have to change strategy in order to use Git. > Otherwise, we have a choice. we have a choice Regards, Hervé > > > Regards, > > > > Hervé > > > > > > [1] > > https://help.github.com/articles/configuring-a-publishing-source-for-gith > > ub-pages/ > > > > [2] > > https://github.com/apache/infrastructure-puppet/blob/deployment/modules/g > > itwcsub/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.ht > > ml#Git_branch
