This is an automated email from the git hooks/post-receive script. adsb pushed a commit to branch master in repository lintian.
commit d03b83a2756aa964c939c512dc0934b8f420698c Author: Adam D. Barratt <a...@adam-barratt.org.uk> Date: Tue Aug 11 19:29:41 2015 +0100 doc/tutorial/*: proof-read Signed-off-by: Adam D. Barratt <a...@adam-barratt.org.uk> --- doc/tutorial/Lintian/Tutorial/TestSuite.pod | 18 +++---- doc/tutorial/Lintian/Tutorial/WritingChecks.pod | 68 ++++++++++++------------- doc/tutorial/Lintian/Tutorial/WritingTests.pod | 42 +++++++-------- 3 files changed, 64 insertions(+), 64 deletions(-) diff --git a/doc/tutorial/Lintian/Tutorial/TestSuite.pod b/doc/tutorial/Lintian/Tutorial/TestSuite.pod index 650fd26..1a87ed8 100644 --- a/doc/tutorial/Lintian/Tutorial/TestSuite.pod +++ b/doc/tutorial/Lintian/Tutorial/TestSuite.pod @@ -18,9 +18,9 @@ L<Lintian::Tutorial::WritingTests>. The Lintian test suite is an extensive collection of various test cases. The test suite is divided into 4 "sub-suites". The majority -of all tests are currently located in the "tests" sub-suite. +of tests are currently located in the "tests" sub-suite. -To run the full suite in all of its glory, simply invoke: +To run the full suite in all its glory, simply invoke: $ debian/rules runtests @@ -29,11 +29,11 @@ To run the full suite in all of its glory, simply invoke: $ mkdir -p debian/test-out $ t/runtests -k --dump-logs t debian/test-out -But while writing a new tag (or check) you probably only want to run a +While writing a new tag (or check) you probably only want to run a particular (subset of the) test(s). See L</Running a subset of the tests> for the available options. -When run via I<debian/rules>, the test suite respects the +When run via I<debian/rules>, the test suite respects "DEB_BUILD_OPTIONS=parallel=N". When using I<t/runtests> directly, use I<-jN> to choose the number of threads. Note that "N" denotes the amount of "worker" threads. The test runner will generally have 2 @@ -41,9 +41,9 @@ threads more than that. Also each "worker" will run lintian, which runs multiple unpacking jobs in parallel as well. In case you are wondering about the 2 extra threads in the test -runner, the first of them is the "coordinator"-thread (which will +runner, the first of them is the "coordinator" thread (which will generally be waiting when the workers are active) and the second one -is the "output"-thread (which handles the fancy output). +is the "output" thread (which handles the fancy output). =head2 Running a subset of the tests @@ -72,7 +72,7 @@ To run all tests for a given check, use: $ t/runtests --dump-logs -k t debian/test-out $check $check must be the name of a check (it will test for -checks/$check.desc) or "legacy". This will run all tests that starts +checks/$check.desc) or "legacy". This will run all tests that start with "$check-". Note: The "changes" sub-suite in the new test suite does not support @@ -90,12 +90,12 @@ To run all tests in a given sub-suite, use: $suites is a comma-separated list of names of sub-suites to run. -Note: this cannot be used to influence the order, in which the sub-suites +Note: this cannot be used to influence the order in which the sub-suites are run. =item Running all tests designed for a specific tag -To run all tests that has a "Test-For" or a "Test-Against" for a given +To run all tests that have a "Test-For" or a "Test-Against" for a given tag, use: $ debian/rules runtests onlyrun=tag:$tag diff --git a/doc/tutorial/Lintian/Tutorial/WritingChecks.pod b/doc/tutorial/Lintian/Tutorial/WritingChecks.pod index f9433ab..6f4860b 100644 --- a/doc/tutorial/Lintian/Tutorial/WritingChecks.pod +++ b/doc/tutorial/Lintian/Tutorial/WritingChecks.pod @@ -17,17 +17,17 @@ one. =head1 DESCRIPTION -The basics of writing a check is outlined in the Lintian User Manual -(§3.3). This tutorial will focus on the part of writing the actual +The basics of writing a check are outlined in the Lintian User Manual +(§3.3). This tutorial will focus on the act of writing the actual check. In this tutorial, we will assume the name of the check to be -written is called "deb/pkg-check". +written is "deb/pkg-check". The tutorial will work with a "binary" and "udeb" check. Checking source packages works in a similar fashion. =head2 Create a check I<.desc> file -As mentioned, this tutorial will focus on the part of writing a check. +As mentioned, this tutorial will focus on the writing of a check. Please see the Lintian User Manual (§3.3) for how to do this part. =head2 Create the Perl check module @@ -48,7 +48,7 @@ Start with the template: return; } -This snippet above is a simple valid check that does "nothing at all". +The snippet above is a simple valid check that does "nothing at all". We will extend it in just a moment, but first let us have a look at the arguments at the setup. @@ -70,7 +70,7 @@ At the moment, $type is one of "binary" (.deb), "udeb", "source" (.dsc) or "changes". This argument is mostly useful if certain checks do not apply equally to all package types being processed. -Generally it is advisable to do check only binaries ("binary" and +Generally it is advisable to check only binaries ("binary" and "udeb"), sources or changes in a given check. But in rare cases, it makes sense to lump multiple types together in the same check and this argument helps you do that. @@ -110,7 +110,7 @@ This is an instance of L<Lintian::ProcessableGroup>. =back -Now back to the part of coding. +Now back to the coding. =head2 Emitting a tag @@ -148,15 +148,15 @@ Lintian/your check. =head2 Accessing fields -Lets do a slightly harder example. Assume we wanted to emit a tag for +Let's do a slightly harder example. Assume we wanted to emit a tag for all packages without a (valid) Multi-Arch field. This requires us to A) identify if the package has a Multi-Arch field and B) identify if -the contents of the field was valid. +the content of the field was valid. Starting from the top. All $info objects have a method called field, which gives you access to a (raw) field from the control file of the package. It returns C<undef> if said field is not present or the -contents of said field otherwise. Note that field names must be given +content of said field otherwise. Note that field names must be given in all lowercase letters (i.e. use "multi-arch", not "Multi-Arch"). # deb/pkg-check is loaded as Lintian::deb::pkg_check @@ -179,7 +179,7 @@ in all lowercase letters (i.e. use "multi-arch", not "Multi-Arch"). return; } -This was the first half. Lets look at checking the value. Multi-arch +This was the first half. Let's look at checking the value. Multi-arch fields can (currently) be one of "no", "same", "foreign" or "allowed". One way of checking this would be using the regex: @@ -239,17 +239,17 @@ pre-depend on the package "multiarch-support". Well, we could use the L<< $info->relation|Lintian::Collect::Binary/relation (FIELD) >> method for this. -The $info->relation returns an instance of L<Lintian::Relation>. This +$info->relation returns an instance of L<Lintian::Relation>. This object has an "implies" method that can be used to check if a package has an explicit dependency. Note that "implies" actually checks if -one relations "implies" another (i.e. if you satisfied relationA then +one relation "implies" another (i.e. if you satisfied relationA then you definitely also satisfied relationB). -Like with the "field"-method, field names have to be given in all -lowercase. But "relation" will never return C<undef> (not even if the +As with the "field"-method, field names have to be given in all +lowercase. However "relation" will never return C<undef> (not even if the field is missing). -So in example: +For example: my $predepends = $info->relation('pre-depends'); unless ($predepends->implies('multiarch-support')) { @@ -296,7 +296,7 @@ Inserted in the proper place, our check now looks like: =head2 Using static data files Currently our check mixes data and code. Namely all the valid values -for the Multi-Arch field is currently hard-coded in our check. We can +for the Multi-Arch field are currently hard-coded in our check. We can move those out of the check by using a data file. Lintian natively supports data files that are either "sets" or @@ -335,7 +335,7 @@ Data files work with 3 access methods, "all", "known" and "value". =item all "all" (i.e. $data->all) returns a list of all the entries in the data -files (for key/value tables, all returns the keys). The list is not +file (for key/value tables, all returns the keys). The list is not sorted in any order (not even input order). =item known @@ -405,7 +405,7 @@ So the resulting check is: =head2 Accessing contents of the package -Another very used mechanism is to check for the presence (or absence) +Another heavily used mechanism is to check for the presence (or absence) of a given file. Generally this is what the L<< $info->index|Lintian::Collect::Package/index (FILE) >> and L<< $info->sorted_index|Lintian::Collect::Package/sorted_index >> methods @@ -413,8 +413,8 @@ are for. The "index" method returns instances of L<Lintian::Path>, which has a number of utility methods. If you want to loop over all files in a package, the sorted_index will -do this for you. If you are looking for a specific file (or dir), a -call to "index" will be much faster. For the contents of a specific dir, +do this for you. If you are looking for a specific file (or directory), a +call to "index" will be much faster. For the contents of a specific directory, you can use something like: if (my $dir = $info->index('path/to/dir/')) { @@ -428,7 +428,7 @@ Keep in mind that using the "index" or "sorted_index" method will require that you put "unpacked" in Needs-Info. See L</Keeping Needs-Info up to date>. -There is also a pair of methods for accessing the control files of a +There are also a pair of methods for accessing the control files of a binary package. These are L<< $info->control_index|Lintian::Collect::Package/control_index (FILE) >> and L<< $info->sorted_control_index|Lintian::Collect::Package/sorted_control_index >>. @@ -442,22 +442,22 @@ L<< $info->index|Lintian::Collect::Package/index (FILE) >>. These methods will open the underlying file for reading (the latter applying a gzip decompression). -However, please do assert that file is safe to read by calling +However, please do assert that the file is safe to read by calling L<is_open_ok|Lintian::Path/is_open_ok> first. Generally, it will only be true for files or safely resolvable symlinks pointing to files. Should you attempt to open a path that does not satisfy those criteria, L<Lintian::Path> will raise a trappable error at runtime. -Alternatively, if you access to the underlying file object, you can +Alternatively, if you access the underlying file object, you can use the L<fs_path|Lintian::Path/fs_path> method. Usually, you will want to test either L<is_open_ok|Lintian::Path/is_open_ok> or L<is_valid_path|Lintian::Path/is_valid_path> first to ensure you do not follow unsafe symlinks. The "is_open_ok" check will also assert -that it is not (e.g.) a named pipe and such. +that it is not (e.g.) a named pipe or such. Should you call L<fs_path|Lintian::Path/fs_path> on a symlink that -escape the package root, the method will throw a trappable error at +escapes the package root, the method will throw a trappable error at runtime. Once the path is returned, there are no more built-in fail-safes. When you use the returned path, keep things like "../../../../../etc/passwd"-symlink and "fifo" pipes in mind. @@ -500,7 +500,7 @@ separated list and each element of Y basically falls into 3 cases. =over 4 -=item * The element is a the word I<none> +=item * The element is the word I<none> In this case, the method has no "external" requirements and can be used without any changes to your Needs-Info. The "field" method @@ -510,7 +510,7 @@ This only makes sense if it is the only element in the list. =item * The element is a link to a method -In this case, the method uses another method to do is job. An example +In this case, the method uses another method to do its job. An example is the L<sorted_control_index|Lintian::Collect::Binary/sorted_control_index> method, which uses the @@ -527,13 +527,13 @@ you have to put "bin-pkg-control" in your Needs-Info. =back CAVEAT: Methods can have different requirements based on the type of -package! Example being "changelog", which requires "changelog-file" +package! An example of this "changelog", which requires "changelog-file" in binary packages and "Same as debfiles" in source packages. =head2 Avoiding security issues Over the years a couple of security issues have been discovered in -Lintian. The problem is people can in theory create some really nasty +Lintian. The problem is that people can in theory create some really nasty packages. Please keep the following in mind when writing a check: =over 4 @@ -548,12 +548,12 @@ CVE-2009-4014). Usually 3-arg open and the non-shell variant of system/exec are enough. When you actually need a shell pipeline, consider using L<Lintian::Command>. It also provides a I<safe_qx> command to assist -with capturing stdout as alternative to `$cmd` (or qx/$cmd/). +with capturing stdout as an alternative to `$cmd` (or qx/$cmd/). =item * Do not trust field values. This is especially true if you intend to use the value as part of a -file name. Verify that field contains what you expect before you use +file name. Verify that the field contains what you expect before you use it. =item * Use L<Lintian::Path> (or, failing that, is_ancestor_of) @@ -571,7 +571,7 @@ You might be tempted to think that the following code is safe: } This is definitely unsafe if "$filename" contains at least one -directory segment. So if in doubt, use +directory segment. So, if in doubt, use L<is_ancestor_of|Lintian::Util/is_ancestor_of(PARENTDIR, PATH)> to verify that the requested file is indeed the file you think it is. A better version of the above would be: @@ -600,7 +600,7 @@ Of course, it is much easier to use the L<Lintian::Path> object } Here you can drop the " && $ufile->is_file" if you want to permit -safe-symlinks. +safe symlinks. For more information on the is_ancestor_of check, see diff --git a/doc/tutorial/Lintian/Tutorial/WritingTests.pod b/doc/tutorial/Lintian/Tutorial/WritingTests.pod index 45c9ab6..eb1a145 100644 --- a/doc/tutorial/Lintian/Tutorial/WritingTests.pod +++ b/doc/tutorial/Lintian/Tutorial/WritingTests.pod @@ -6,8 +6,8 @@ Lintian::Tutorial::WritingTests -- Short tutorial on writing tests =head1 SYNOPSIS -This document attempts to be a short / quick tutorial to the lintian -test suite from a test-writer perspective. As such, it will only +This document attempts to be a short / quick tutorial to the Lintian +test suite from a test-writer's perspective. As such, it will only cover the standard type of tests (from the "tests" suite). The guide will involve writing a test for the "deb/pkg-check" check, @@ -18,26 +18,26 @@ For running tests, please see L<Lintian::Tutorial::TestSuite> instead. =head1 DESCRIPTION -The lintian test suite is divided into several parts. These are: +The Lintian test suite is divided into several parts. These are: =over 4 =item * scripts Small (Perl) "prove" tests. These assert that code style, data files -or/and self-contained code units (i.e. unit tests) work as intended. -They are B<not> used for testing lintian tags. +and/or self-contained code units (i.e. unit tests) work as intended. +They are B<not> used for testing Lintian tags. =item * changes / debs / source -These suites are small test suites that tests some particular tags for +These suites are small test suites that test some particular tags for I<.changes>, I<.deb> or I<.dsc> files. Typically, you will find the more exotic tags here, which require some special fiddling and cannot be built by a "standard" dh7 + dpkg build. =item * tests -This suite is the standard test suite for testing lintian tags. +This suite is the standard test suite for testing Lintian tags. =back @@ -46,10 +46,10 @@ With this in mind, let us move on to the scope. =head2 Scope of the tutorial The "tests" suite alone is fairly complex on its own. To keep things -simple, the tutorial itself will limit itself to creating a "native" +simple, the tutorial will limit itself to creating a "native" package with no special requirements in the "tests" suite. -In particular note that the tags I<must not> be I<pedantic> for this +In particular, note that the tags I<must not> be I<pedantic> for this to work. If you followed the check writing tutorial and made the tags pedantic, please change them into "I", "W" or "E" tags. @@ -57,11 +57,11 @@ Once the basics are covered, you should be better equipped to deal with the other ("tag testing") suites or using other features of the "tests" suite (e.g. pedantic tags). -=head2 The design of the lintian test suite +=head2 The design of the Lintian test suite -The basic design of the Lintian test suite can basically be summed up -to I<less is more>. The Debian build system is changing all the time -(albeit, slowly) and some times it deprecates or breaks existing +The basic design of the Lintian test suite can be summed up +as I<less is more>. The Debian build system is changing all the time +(albeit, slowly) and sometimes it deprecates or breaks existing features. With over 400 tests all featuring the same basic parts, the test suite @@ -71,10 +71,10 @@ files to fill in the basic files (e.g. "debian/control" and "debian/changelog"). This means that when a new standards-version comes along, debhelper -deprecates a feature or (more likely) lintian adds a new tag, the +deprecates a feature or (more likely) Lintian adds a new tag, the majority of the tests can quickly be adapted with only a minor effort. -Since pedantic tags tends to require additional effort to avoid, most +Since pedantic tags tend to require additional effort to avoid, most Lintian tests do B<not> run with pedantic tags enabled. =head2 The basics of a "native" package in the "tests" suite @@ -87,7 +87,7 @@ in I<< t/tests/<test-name> >>. This is the test description file. It is a deb822 file (i.e. same syntax as I<debian/control>), which contains a number of fields. -Lets start with the following template: +Let's start with the following template: Testname: pkg-deb-check-general Sequence: 6000 @@ -118,7 +118,7 @@ Please keep the following conventions in mind: =item The Testname should be "<check-name>-<test-name>" Note that regular Lintian checks do I<not> have a "/", so the naming -convention work slightly better there. +convention works slightly better there. =item The Sequence should always be 6000 for tests checking tags. @@ -194,7 +194,7 @@ run by using: $ t/runtests --dump-logs t debian/test-out pkg-deb-check-general -Although, it will not emit the correct tags unless pkg/deb-check is +However, it will not emit the correct tags unless pkg/deb-check is part of the debian/main lintian profile. If your check is a part of a different profile, add the "Profile: <name>" field to the "desc" file. @@ -207,7 +207,7 @@ resources that may be useful to your future test writing work. Basically, the tag-testing test cases all involve building a package and running lintian on the result. The "tests" suite does a full -build with dpkg-buildpackage, the other suites "hand-crafts" only the +build with dpkg-buildpackage, the other suites "hand-craft" only the type of artifacts they are named after (e.g. "source" produces only source packages). @@ -334,7 +334,7 @@ artifact. =item * -Else, copy I<< <test-dir>/<test-name>.changes.in >> into the build dir +Otherwise, copy I<< <test-dir>/<test-name>.changes.in >> into the build dir and use it as a template to create I<< <build-dir>/<test-name>.changes >>. The result is then used as the artifact to test. @@ -367,7 +367,7 @@ syntax as I<debian/control>), which contains a number of fields. This file contains the "expected" output of lintian. -This is generally sorted, though a few tests relies on the order of +This is generally sorted, though a few tests rely on the order of the output. This can be controlled via the "Sort" field in the "desc" file. -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/lintian/lintian.git -- To UNSUBSCRIBE, email to debian-lint-maint-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: https://lists.debian.org/e1zpejj-0002vo...@moszumanska.debian.org