indeed useful. 2016-01-06 18:16 GMT+08:00 Bernd Mathiske <[email protected]>:
> +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 > > -- Deshi Xiao Twitter: xds2000 E-mail: xiaods(AT)gmail.com
