+1. (Really exited about this prospect!) This kind of documentation is not necessarily for “testing” only. How can we expect certain features to run in production if they don’t pass the unit tests on a given platform? So I am in favor of the “let’s expand our existing install instructions” tack. The setup for testing and production should be identical.
It is indeed quite tricky to get any given variant of Linux set up just right for every supported feature and it takes a lot of time to debug the setup script when something goes wrong. In particular when starting from a predefined vagrant file or AMI, which is often the case. I suggest we post “verified" scripts (for a limited set of platforms, arguably the same as in “Getting Started") that explicitly name their starting configuration (vagrant file name, AMI name, or…) and contain all useful commands with comments why they are necessary. “Verified” means that as part of the release process, a committer has checked that the script worked as described for the RC. Bugs can be filed against this kind of documentation. Regarding the problem if a feature depends on an obscure source: I’d suggest that if we cannot name any viable source then we cannot support the feature depending on that component on that platform in the given release. If the source is available during the release and later becomes non-viable, that’s another matter. We should label all commands pertaining to sources that are potentially in danger of changing as such, by source code comments in the scripts. Example for packages that can be regarded as “reliable”: what you can install by straight “apt-get install -y” from an LTS version, without prior repo meddling. BTW: personally, I prefer a script that runs from beginning to end in one swoop to instructions like “open this file in an editor then change the line containing this and that to such and such and add a line that says bla.” Best to have a comment that explains all that next to a sed or similar command that just does it. 2c Bernd > On Dec 17, 2015, at 10:08 PM, Neil Conway <[email protected]> wrote: > > +1 to the general idea of including this information in the documentation. > > I'd probably lean towards including this information in the current > "Getting Started" page, but in a separate section ("Running The Test > Suite"?). > > Neil > > On Thu, Dec 17, 2015 at 12:38 PM, Greg Mann <[email protected]> wrote: >> Hey folks! >> Something occurred to me recently which is related to the extensive testing >> we did in preparation for the 0.26.0 release. Since I started contributing >> to the project, my Source of Truth for "how to prepare a given platform to >> compile and run Mesos" has been the Getting Started page of our >> documentation. However, this doc doesn't provide guidance for all platforms >> on "how to prepare this platform to compile Mesos and then TEST it in all >> configurations", which is crucial information for us when it comes to >> testing, and would be useful to our users as well. I wonder if it makes >> sense to have a separate place in our documentation where we include these >> exhaustive installation instructions, which may be beyond the scope of a >> "Getting Started" document for new users. >> >> One option is to introduce a new documentation section on testing, where we >> can include supplementary installation instructions, as well as information >> on the test suite, how to run it, the available options, etc. We already >> have a page on good patterns to use when *writing* tests, but nothing I can >> find on running the tests, besides a brief mention in "Getting Started". >> >> Another option would be to just expand our existing install instructions to >> be a bit more comprehensive and include instructions for optional >> components like libevent2, docker, kernel updates to enable cgroup tests, >> etc. Especially on an older platform like CentOS 6.6, this can be tricky. >> >> Note that some of these installations (like libevent2 on CentOS 6.6) >> require the use of hard-to-find RPMs whose origin is uncertain, and it's >> possible that we wouldn't want to offer such instructions publicly to our >> users. >> >> Thoughts? >> >> Cheers, >> Greg
signature.asc
Description: Message signed with OpenPGP using GPGMail
