Hi, I would like to gather some opinions on updating upstream README file with Debian specific instructions, e.g. installation through APT and reporting bugs through reportbug. I think this could be a good thing, but currently it is not handled well. I have the following concerns:
* Manually updating upstream README files adds to maintenance cost. When upstream updates their README files, it can cause a merge conflict with the local patch adding Debian specific instructions, and the maintainer needs to spend time to see whether the change is trivial. When upstream wording changes significantly, it could require a substantial rewrite. * Some times the change removes upstream instructions. When adding Debian specific changes to upstream README, some maintainers also remove upstream instructions to install the package from ELPA. While technically ELPA instructions should not be relevant in a Debian installation, I'm not sure removing such information is a good thing to the users. One example is when a package is orphaned, and upstream has newer versions released, a user can actually get those newer version through ELPA before a new maintainer adopts and updates the package in Debian. This also applies to addons in a stable distribution without recent backports. * This is not done consistently. I saw some of the addons having this treatment but not all of them. And due to the ad-hoc nature, the wording varies among the packages, and it is hard to update the instructions consistently, e.g. when a package foo-mode is elpafied and changed to elpa-foo-mode and we need to update the package name. As a preliminary thought, I think a better place to add Debian specific instruction is probably the README.Debian file, which is a natural place for Debian specific information, and avoids the previous mentioned downsides by not touching upstream files. We may also make it a template and generate the installation, removal, and bug reporting sections if desired. I understand that some packages already make use of this file for package specific instructions, so this would need some care to avoid any conflicts. Another angle to look at the issue is that if a user gets an Emacs addon through a Debian package, the user should be sufficiently familiar with how Debian works. That could be true. Meanwhile I think providing some Debian instructions, especially Emacsen specific instructions, is still a good thing. Would be great to hear the opinions from others. -- Regards, Xiyue Deng
signature.asc
Description: PGP signature
