A general comment: although this TUTORIAL file originally was just meant to reflect one talk from 2015, I recommend letting it evolve to be _the_ tutorial for using autopkgtest in the Debian CI environment, because this is one link that search engines find when someone searches for "autopkgtest tutorial", and it has "tutorial" in its name. There are autopkgtest information files all over the place, and it isn't immediately clear which should be an "official" Debian reference tutorial.
Ideally this TUTORIAL file could evolve into _the_ tutorial, rather than having someone go through every link they can find trying to piece things together (which is what I did). On Tue, Sep 4, 2018 at 11:59 AM Paul Gevers <elb...@debian.org> wrote: > ... > You're looking at this file: > https://salsa.debian.org/ci-team/debci/blob/master/docs/TUTORIAL.md > > It would be awesome if you could propose changes to that file instead of > the generated html file. However, I already have some comments. I did not know that the HTML document I changed had its origin in another format. I _could_ modify the md file, but I do not work in md usually and I would be taking a chance of something being lost in translation. If nobody who is familiar with the Debian md format has time I can do that, but then please compare any formatting with the HTML file that I submitted; I do know HTML well and what I did there is what I intended. HTML is my native language. :-) > > On 03-09-18 06:42, Paul Hardy wrote: > > Please consider adding "The test environment" section (or something > > like it) that I added to the autopkgtest tutorial page. It gives an > > introductory description of the general environment in which a CI test > > script runs in a way that I have not found elsewhere. > > Although I appreciate what you try to do here, it rather feels weird, as > you are just describing a very standard Debian setup. I really think > this is not the place to describe how Debian works and where packages > install their files. Policy already does that. So your first paragraph > could be "The test environment is a minimalistic standard Debian > installation." That is good, but I would still make it clear that the installation is not in some sub-tree (for example, /var/tmp/ci/sid/...). I would explicitly mention as an example that data files for "mypackage" are in "/usr/share/mypackage". That should get the point across. > > Your second sentence basically repeats stuff that is in the autopkgtest > spec. Maybe we should more clearly link that? > https://salsa.debian.org/ci-team/autopkgtest/raw/master/doc/README.package-tests.rst I think that AUTOPKGTEST_TMP, etc., is so important that it merits mentioning directly in the document. Not everyone will click a link; put the information in this TUTORIAL document where it cannot be missed. > > $PATH will just contain the default Debian $PATH, again, I think this is > described in Debian policy. The location of the scripts is described in > the spec again. Yes, but I didn't know that the files were installed with "/" as the absolute top-level directory when I began. I recommend conveying that somehow explicitly. Because I only knew that installed binaries could be located using $PATH from the "trivial example" and the bug report that initiated that example, this is what the debian/tests/control file did for utfcheck-1.1-2: Test-Command: cd test && progloc=`which utfcheck` && utfcheck_bindir=`dirname $progloc` ./test-all Now that I know, for example, that my utfcheck program is installed as per the FHS (and not in some sub-tree for example under /var/tmp/ci/sid/usr/bin using $DESTDIR), the debian/tests/control file for utfcheck-1.2-1 (my most recent upload) has simplified the above to Test-Command: cd test && utfcheck_bindir=/usr/bin ./test-all Does this example make it clear what I did not understand from the autopkgtest and CI documentation? So I recommend adding enough to make it clear that absolute file locations are per the FHS and Debian Policy. You can say that in an abbreviated way compared to what I wrote in the HTML file I sent, but not so abbreviated that it might require the kind of experimentation that I did with utfcheck-1.1-2 and -1.2-1 (and I'm still not done; I want to simplify it further by just being able to say "make installcheck", incorporating what I learned into my Makefiles). When I get that far, I intend to write up what I did to get everything to work between GNU Autotools, autopkgtest in the Debian CI environment, and test scripts in the source tree that work on many systems (not just with autopkgtest). > ... > > I copied the two paragraphs that describe AUTOPKGTEST_TMP and > > AUTOPKGTEST_ARCHIVE from > > > > https://people.debian.org/~mpitt/autopkgtest/README.package-tests.html > > Hmm, we live on salsa nowadays, please follow the link above. And > instead of repeating stuff, can't we make smart text around links? I recommend directly adding mention of those two environment variables in this TUTORIAL document. You can always also give someone a link to a file on salsa as a footnote. I thought Martin's descriptions were perfectly clear and not in need of re-wording. I think it is useful to explicitly mention AUTOPKGTEST_TMP before providing the first example test script. Does the CI Team and/or autopkgtest Team think they can take what I wrote in the HTML file, simplifying it a little as additions to the md file with wording they prefer? I understand this stuff now so it will not benefit me; it is to benefit others who think the same ambiguity about installed file location existed. Thank you, Paul Hardy
