mesos-reviews mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benjamin Mahler <bmah...@apache.org>
Subject Re: Review Request 52064: Support for multiple versions of docs.
Date Mon, 12 Feb 2018 22:28:11 GMT


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


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message