This is an automated email from the git hooks/post-receive script. nthykier pushed a commit to branch master in repository lintian.
commit 5131a177724305aabd5387248e91f33f944107ca Author: Niels Thykier <ni...@thykier.net> Date: Sat Sep 17 09:38:52 2016 +0000 Add a separate CONTRIBUTING.md file Signed-off-by: Niels Thykier <ni...@thykier.net> --- CONTRIBUTING.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 23 +------ 2 files changed, 202 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0881ecf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,201 @@ +How to contribute to Lintian +============================ + +This document is intended for prospective and existing contributors. + +The first section will cover how to get started for new comers. After +that is a section on recommended practices and additional resources. + +Getting started +--------------- + +Please checkout the repository from anonscm.debian.org: + + $ git clone https://anonscm.debian.org/git/lintian/lintian.git + $ cd lintian + +You will also need a number of dependencies. On a very recent Debian +(e.g. Stretch), you can have apt install these for you via: + + $ apt-get build-dep debian/control + +Otherwise, the full list of dependencies are listed in the `Build-Depends*` +fields in the `debian/control` file. + +#### API Docs, tutorials and the test suite documentation + +We also have some short tutorials in our API docs. You can compile +the API documentation via: + + $ debian/rules api-doc + $ sensible-browser doc/api.html/index.html + +From there, you might want to start with "Lintian::Tutorial". If you +prefer to use perldoc (or want to improve the tutorials), you can find +the source files for the tutorial in doc/tutorial. + +The tutorial briefly covers: + + * How to write a (Lintian) check + * How to write a test case + * How to use the test runner (efficiently) + +We are very happy to receive improvements to the tutorials or other +documentation as well. + +There is also an online copy on the [Lintian web site][online-api-docs]. +Note that the online copy does not necessarily reflect the API of the +current development version of Lintian. Instead, it is the API of +Lintian when it was last updated on the Lintian web site. + +[online-api-docs]: https://lintian.debian.org/library-api/index.html + +Making changes +-------------- + + * Make commits of logical units + * Add a test for your change - especially if you introduce a new tag + (run with: `debian/rules runtests onlyrun=<testname>`) + * Check the changes for style issues + (`debian/rules runtests onlyrun=suite:scripts`) + * Check the changes against the test suite + (`debian/rules runtests`) + * Please format the commit messages with a short synopsis and (optionally) a long description. Example: + +```` + Add =encoding to the POD in Lintian::Collect + + We use a UTF-8 section symbol, and the current version of Pod::Simple + therefore requires explicitly declaring the character set. +```` + +For more on best practices on git commit messages, please review +[A Note About Git Commit Messages][tbaggery-git-commit] for inspiration. + + +[tbaggery-git-commit]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html + +Submitting changes +------------------ + +Please submit your changes to the Debian Bug Tracker by reporting a bug +against the `lintian` package. On a Debian system, this can usually +be done by using `reportbug`: + + $ reportbug lintian + +Otherwise send a plain text mail to "<sub...@bugs.debian.org>" with +the first line being `Package: lintian`: + +You are welcome to attach the changes to the bug report or link to a +git branch. If you use attachments, please generate the changes via +the `git format-patch` command. + +Recommended practices +===================== + + +Code style dictated by perltidy and perlcritic +---------------------------------------------- + +For consistency, perltidy is used to normalize the style of the Perl +code in Lintian. This is enforced via tests and will be checked +in all submissions. In the cases where perltidy fails miserably, +please format the piece manually and use a "no perltidy" rule. As +an example: + +```` + #<<< no perltidy + something + that perltidy should not touch + #>>> + +```` + +Beyond perltidy, we also use perlcritic to enforce some semantic +rules. An example rule being that we forbid the use of `grep` in +boolean context (which is better done via the `any` sub from +`List::Util`). + +We have enabled enforcements of the rules, which lintian already +follows and which made sense to lintian. + +The "master" branch is "always releasable" +------------------------------------------ + +Generally the "master" branch should kept in a state where it is always +releasable. This is an accepted practice by many other projects and +also helps us in case we suddenly need to do a release. + +You are always welcome to create topic branches for publishing code that +is not ready for a release yet. + +Updating debian/changelog +------------------------- + +If you are not a committer, you are welcome to leave this out and let +the committer write this bit for you. It often makes easier for us to +merge your changes as the changelog is notorious for merge conflicts. + +The general format is: + + * checks/phppear.{desc,pm}: + + [JW] Fix typo. + + [NT] Apply patch from Jochen Sprickerhof to skip this check if the + package does not contain any php files. (Closes: #805076) + * checks/testsuite.pm: + + [JW] Apply patch from Sean Whitton to recognise autopkgtest-pkg-elpa + as a valid value for the Testsuite field. (Closes: #837801) + + * data/files/php-libraries: + + [JW] Apply patch from Marcelo Jorge Vieira to update package name + for php-gettext. (Closes: #837502) + + * lib/Lintian/*.pm: + + [JW] Fix typos. + * lib/Lintian/Tags.pm: + + [JW, NT] Fix mojibake in UTF-8 encoded comments for overrides. + (Closes: #833052) + +Beyond the regular rules for Debian changelog files, the general +guidelines are: + + * The message is prefixed with the intials of the committer(s). New + committers, please remember to add yourself to debian/copyright. + * Changes are grouped by "root" folder ("checks", "data" and "lib" in + the example above). + * The groups are sorted by the name of the "root" folder and separated + by a single line. + * Inside a "root" folder, changes are grouped by files and sorted by + the ("earliest") file in the group. + * Changes to the test suite are generally only documented if it has a + "visible" effect (e.g. closes a "FTBFS" bug). + * If a change effects more than one "root" folder, they are repeated + for each of the related "root" folders. + * Text after a period is followed by *two* spaces (except where it is + part of a abbreviation like "e.g."). + +Backport requirements +--------------------- + +There are some limits to which changes Lintian can accept as it needs +to be backportable to the current Debian stable release. As such, +all dependencies must be satisfied in Debian stable or stable-backports. + +There are several reasons for this requirement. The two primary being: + + * Lintian is run on various debian.org hosts which are all running + Debian stable (lintian.debian.org and ftp-master.debian.org) + + * A lot of developers use stable and will easy access to an up to date + lintian. + +Accordingly, we have continuous integration job running on +jenkins.debian.net to test this. + +Additional resources +==================== + + * perldoc [doc/tutorial/Lintian/Tutorial.pod]() + * perldoc [doc/README.developers]() + * perldoc [doc/README.release]() diff --git a/README.md b/README.md index 87edf81..759bad6 100644 --- a/README.md +++ b/README.md @@ -84,28 +84,7 @@ Developing/Patching Lintian =========================== If you are interested in working developing patches for Lintian or -just writing your own Lintian checks, please download the Lintian -source and consider reading the doc/README.developers from the source -tree: - - $ perldoc doc/README.developers - -We also have some short tutorials in our API docs. You can compile -the API documentation via: - - $ debian/rules api-doc - $ sensible-browser doc/api.html/index.html - -From there, you might want to start with "Lintian::Tutorial". If you -prefer to use perldoc (or want to improve the tutorials), you can find -the source files for the tutorial in doc/tutorial. - -There is also an online copy on the [Lintian web site][online-api-docs]. -Note that the online copy does not necessarily reflect the API of the -current development version of Lintian. Instead, it is the API of -Lintian when it was last updated on the Lintian web site. - -[online-api-docs]: https://lintian.debian.org/library-api/index.html +just writing your own Lintian checks, please review [CONTRIBUTING.md](). Feedback ======== -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/lintian/lintian.git