4.14. Source package handling: debian/README.source

If running dpkg-source -x on a source package doesn’t produce the source of the package, ready for editing, and allow one to make changes and run dpkg-buildpackage to produce a modified package without taking any additional steps, creating a debian/README.source documentation file is recommended. This file should explain how to do all of the following:

1. Generate the fully patched source, in a form ready for editing, that would be built to create Debian packages. Doing this with a patch target in debian/rules is recommended; see Main building script: debian/rules.

2. Modify the source and save those modifications so that they will be applied when building the package.

3. Remove source modifications that are currently being applied when building the package.

4. Optionally, document what steps are necessary to upgrade the Debian source package to a new upstream version, if applicable.

This explanation should include specific commands and mention any additional required Debian packages. It should not assume familiarity with any specific Debian packaging system or patch management tools.

This explanation may refer to a documentation file installed by one of the package’s build dependencies provided that the referenced documentation clearly explains these tasks and is not a general reference manual.

debian/README.source may also include any other information that would be helpful to someone modifying the source package. Even if the package doesn’t fit the above description, maintainers are encouraged to document in a debian/README.source file any source package with a particularly complex or unintuitive source layout or build system (for example, a package that builds the same source multiple times to generate different binary packages).