> On Feb. 9, 2018, 6:02 p.m., Benjamin Bannier wrote: > > I am wondering whether it wouldn't be simpler to have the site setup just > > generate output for the currently checked-out version and dump that into > > some version-specific output folder. We could then have some CI setup > > execute this for the different tags or branches we care about. This > > wouldn't only simplify the site setup, but probably also deal better with > > e.g., changed requirements to the base system (e.g., needed to build > > binaries generating the endpoint documentation) which are currently not > > managed in the rake file. > > > > One difficulty with that approach would be to determine under what branch > > we are actually working on. My guess is that we wouldn't want to update to > > documentation of 1.3.0 until we have tagged a 1.3.0 version, so we'd likely > > build documentation for the n-latest tags. The `HEAD` of `master` is more > > tricky as it would change more frequently and not directly have a release > > tag as parent (these live on release branches) making it harder to work > > with say `git-describe`. Maybe we could parse this from source, e.g., > > `MESOS_VERSION` in `include/mesos/version.hpp`. > > > > The other difficulty might be that we might move a lot of site-generation > > setup out of the repo into e.g., Jenkins config. There are probably ways to > > work around that, but I haven't thought that through. > > Tim Anderegg wrote: > I'm not familiar with how Jenkins is configured and used here, but your > approach could be simpler depending on how complex the CI build setup is. > This patch would remain mostly the same, except lines 68-89 of the Rakefile > could be removed and the git dependency would no longer be necessary. The > version could then be fed in by Jenkins, which would probably be > easier/simpler than trying to programmatically determine the version. Right > now "master" just translates to "latest" in the patch as-is. > > I saw putting everything in the Rakefile as the most straightforward > approach, since it allows the correct versions to generate docs for to be > determined programmatically, avoiding the difficulty you mentioned above. > However, it does require generating all documentation for all versions on > each build, and significant changes to the build process or documentation > process down the road might make it difficult to maintain a > backwards-compatible approach (e.g. I currently disable doc generation for > the oldest dozen tags or so which don't have the same documentation setup, or > any documentation at all).
I tend to prefer the approach Benjamin's suggested above since the documentation generation will be versioned alongside the documentation, so that we don't have to deal with backwards compatibility of documentation generation on HEAD. - Benjamin ----------------------------------------------------------- This is an automatically generated e-mail. To reply, visit: https://reviews.apache.org/r/52064/#review197173 ----------------------------------------------------------- On Feb. 9, 2018, 1:46 a.m., Tim Anderegg wrote: > > ----------------------------------------------------------- > This is an automatically generated e-mail. To reply, visit: > https://reviews.apache.org/r/52064/ > ----------------------------------------------------------- > > (Updated Feb. 9, 2018, 1:46 a.m.) > > > Review request for mesos, haosdent huang and Vinod Kone. > > > Bugs: MESOS-3011 > https://issues.apache.org/jira/browse/MESOS-3011 > > > Repository: mesos > > > Description > ------- > > Support for multiple versions of docs. > > > Diffs > ----- > > site/Gemfile 877fe914a9787c140848fdf9958571fec5fa58ff > site/Gemfile.lock 909f3f3badeaa47c80929e243ce36307766edee4 > site/Rakefile 31ef6ffe225ce7ddc573054058af1070b9e96b09 > site/config.rb 04bc7aa1e0ac61ce5d89fd53d32f265532996913 > site/data/releases.yml e3edc308a5429585b3fc3f05564d695ba3217035 > site/source/assets/js/versions.js PRE-CREATION > site/source/layouts/basic.erb 8a07488940f3793d6fdd291dbe896e098f321c96 > > > Diff: https://reviews.apache.org/r/52064/diff/6/ > > > Testing > ------- > > Testing was done manually to verify that the documentation was built for each > version of Mesos that is supported (some older versions do not have > compatible documentation). > > > Thanks, > > Tim Anderegg > >
