1 files changed, 189 insertions, 0 deletions
diff --git a/doc/README.developers.pod b/doc/README.developers.pod
new file mode 100644
index 0000000..640f629
--- /dev/null
+++ b/doc/README.developers.pod
@@ -0,0 +1,189 @@
+# -*- pod -*-
+#
+# Use "perldoc doc/README.developers.pod" to read it like a manpage.
+
+=head1 NAME
+
+README.developers.pod -- README file for developers of Lintian
+
+=head1 SYNOPSIS
+
+This document aims to give an overview of the Lintian internals
+and is intended for people, who wants to develop or work on Lintian.
+
+For how to use Lintian, please refer to the (other) README, the manual
+page lintian(1) or the User Manual.
+
+=head1 DESCRIPTION
+
+Lintian dissects Debian packages and tries to find bugs and policy
+violations. It contains automated checks for many aspects of Debian
+policy as well as some checks for common errors.
+
+This document describes how you can contribute to Lintian's
+development as well as adapt it to your needs.
+
+Lintian has a large code base which has as its starting point the
+directory "bin". This directory holds the "lintian" executable.
+This is what gets called when a user calls lintian. This frontend
+then calls the lintian checks which run over the Debian package
+that Lintian is checking.
+
+=head2 The source code layout
+
+The source code is divided into self-contained groups.  Here is a
+quick overview.
+
+=over 4
+
+=item checks
+
+contains the checks and the tag descriptions.
+
+=item collection
+
+contains unpacking scripts
+
+=item data
+
+Symlink to the data set for the Debian vendor profiles.  See entry for
+vendors below.
+
+=item debian
+
+contains Debian packaging
+
+=item doc
+
+contains the User Manuals and general docs (see man/ below)
+
+=item bin
+
+contains the frontends (e.g. code installed in /usr/bin)
+
+=item lib
+
+contains Perl modules/library for common tasks.
+
+=item man
+
+contains the manpages for tools in bin/
+
+=item private
+
+various private helpers etc.
+
+=item profiles
+
+contains vendor profiles
+
+=item reporting
+
+tools/code for the lintian.d.o setup
+
+=item t
+
+the new test suite
+
+=item vendors
+
+Per vendor data sets used by checks (and Lintian::Architecture) via
+the Lintian::Data API.  Data set is stored in I<vendors/profilename/data>,
+where I<profilename> is the "full name" of the profile (e.g. ubuntu/main).
+
+=back
+
+=head2 Core concepts in Lintian
+
+In Lintian there are a number of concepts (or terms), here is a list of the
+most important ones:
+
+=over 4
+
+=item Check
+
+A library checking specific aspects of a package, changes file,
+etc. which usually can emit multiple tags.
+
+=item Emit (Tag)
+
+Tag that was not suppressed and was triggered.
+
+=item Lab(oratory)
+
+The Laboratory is Lintian's private little play-ground.  When Lintian
+is asked to process a package, it will generally unpack (parts of) the
+package in the laboratory. The laboratories  expire as soon as Lintian
+is done with them, unless the option '--keep-lab' was specified.
+
+Note that the laboratory is usually abbreviated to "Lab".
+
+=item Overridden (Tag)
+
+Tag that was overridden by the maintainer.  Usually it means that the
+maintainer believes Lintian misdiagnosed the issue.  In some cases it
+is also used for tags that does not handle "corner-cases"
+
+Overridden tags are not displayed by default, but they are still
+counted in statistics.  This should not be confused with "Suppressed".
+
+=item Suppressed (Tag)
+
+Tags that are suppressed cannot be emitted.
+
+Note that suppressed tags are ignored by Lintian, so they are not
+counted in statistics.  Not to be confused with "Overridden".
+
+=item Tag
+
+Issue reported by Lintian.
+
+=item Test
+
+An internal test of Lintian.
+
+=back
+
+=head2 Useful tricks
+
+There is an extended description of tricks on
+L<https://wiki.debian.org/Teams/Lintian/HackersGuide>, but some of them
+are also listed here.
+
+=head3 Running lintian from the git repository
+
+Lintian was designed to be run directly from the git repository.  This
+allows you to quickly test your changes on a live package.  In Lintian
+2.5.18, the frontends will automatically detect when they are being
+run from a source checkout and do the right thing.  Earlier versions
+need LINTIAN_BASE (or --root).  The following shell snippet can be
+used for 2.5.17 and earlier:
+
+ #!/bin/sh
+ # ONLY FOR << 2.5.18~ OR EARLIER.  Lintian (>= 2.5.18~) will DTRT.
+ LINTIAN_BASE="<INSERT PATH TO LINTIAN GIT DIR>"
+ export LINTIAN_BASE
+ exec "$LINTIAN_BASE/bin/lintian" "$@"
+
+Beware of two things: If LINTIAN_BASE is not set, Lintian (<< 2.5.18~)
+will attempt to use the code from the installed version (in
+/usr/share/lintian).
+
+The other issue is that Lintian needs a C.UTF-8 (or an en_US.UTF-8)
+locale.  If this is absent, it may trigger some issues with some
+(e.g. manpage) checks.  With libc-bin from Wheezy and Lintian 2.5.5,
+this is no longer an issue.
+
+=head2 collections and checks
+
+Collections (as the names suggests) are used to extract or/and
+structure data from a package.  This data is then used by the checks
+(usually via Lintian::Collect API) to examine the package.
+
+The check may be doing the extraction (or structuring) of data itself,
+but it should generally be avoided for "heavy" tasks.  Unlike checks,
+collections can (and generally are) run in parallel to improve the
+effective runtime.
+
+=cut
+