diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..791c2ea --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,194 @@ +# Contributing to debhelper + +Thanks for your interest in improving debhelper. + +No matter how you identify yourself or how others perceive you: we +welcome you. We welcome contributions from you as long as they +interact constructively with our community. See also [Code of +Conduct, Social rules and conflict +resolution](#code-of-conduct-social-rules-and-conflict-resolution). + +This document will cover what you need to get started on working with +debhelper, where to submit patches or contributions and what we expect +from contributors. + + +## Getting started + +<a id="getting-starting"></a> + +This section helps you get started with working on debhelper. It +assumes you are comfortable with `git`. + +First clone the debhelper git repository and install build-dependencies: + + git clone https://salsa.debian.org/debian/debhelper.git + cd debhelper + apt-get build-dep ./ + # Used for running the test suite + apt-get install perl + +Running the test suite: + + # Available from the perl package. + prove -lr -j`nproc` t + + +Doing a test build / release build of debhelper: + + # Consider doing it in a chroot to verify that the Build-Depends are correct. + dpkg-buildpackage -us -uc + # installing it for further testing + apt-get install ../debhelper_<version>_all.deb + + +Please have a look at `doc/PROGRAMMING`, which have guidelines for +debhelper code. + + +## Balancing simplicity, ease-of-use, performance, etc. + +At times, there are conflicting wishes for debhelper. We cannot +satisfy all requirements and we sometimes have to say no thanks to a +particular change because it conflicts with design goal, or if it is +better suited in a different project, etc. + +Here are some guidelines that may be useful: + + * New build systems or helpers that are language/framework specific + or have a narrow scope are generally better shipped in a separate + package. If the scope becomes more general, the tooling can be + merged in to debhelper at a later stage. + + * Examples: Most `dh-*` packages in Debian are examples of this. + + * Changes that affect performance considerably generally must only + affect packages that need them and only affect a limited subset of + packages and a limited subset of `dh_*`-tools. Particularly, be + careful of `Dpkg::*`-modules, which tend to have very high load + costs. + + * Helpers / tools should generally *do the right thing* by default + (subject to backwards compatibility). If most people need some + particular option to make the tool work for them, then the default + should be changed (again, subject to backwards compatibility). + + +## Handling backwards compatibility for consumers + +While changes in debhelper should avoid breaking consumers, some times +we need to implement a backwards incompatible change (e.g. to improve +defaults to match the current packaging norms or fix a bug). + + * For non-trivial breakage, we use compat bumps and migrate to the new + functionality by default in the new major version of debhelper. + (see the `compat` function) + + * For trivial issues or (mostly) unused functionality/bugs, then we + can make exceptions. Preferably, have all consumers migrate away + from the feature being changed (in Debian `unstable`) before + applying it. + +Note that we tend to support compat levels for a long time (10+ +years). When changing behaviour via a compat bump, please take an +extra look to ensure the change is sufficient (this is easier said +than done). See `doc/SUPPORT-POLICY` for more information. + +## Debian support baseline for debhelper + +The debhelper project aims to support the Debian `unstable`, +`testing`, and `stable-backports` suites by default. For this to work, +we work based on the following guidelines: + + 1) it should be trivial to use/Build-Depend on debhelper in + `stable-backports`, and + 2) the debhelper in `stable-backports` should behave the same as + in `testing` when backporting a package from `testing`. + + * Note that we do not require feature/bug compatibility with + debhelper in `stable` (as most packages will still use + debhelper from `stable`). + +In some cases, we can disable some *minor* functionality in +`stable-backports` (previous cases being `dbgsym` and `R³`). + +Where possible, use versioned `Breaks` against other packages to +make it easier to support packages in `stable-backports` +(e.g. debhelper had a `Breaks` against `meson` to ensure packages +used a recent enough version of `meson` when using the debhelper +from `stretch-backports`). + +## Submitting your contribution + +We accept merge requests on [salsa.debian.org] and in general prefer +these to bug reports with patches. This is because the merge requests +will run our CI to ensure the tests still pass. When opening a merge +request, please consider allowing committers to edit the branch as +this enables us to rebase it for you. + +However, we fully respect that not everyone may want to sign up on a +Debian service (e.g. it might be a steep overhead for a one-time +contribution). Therefore, we also accepts bug reports against the +debhelper package in Debian with either patches (`git format-patch` +format preferred) or links to public git repositories with reference +to branches. Please see [Submitting a bug +report](#submitting-a-bug-report) for the guide on how to do that. + +Please see [getting started](#getting-started) for how to obtain the +source code and run the test suite. + +[salsa]: https://salsa.debian.org/debian/debhelper + + +## Submitting a bug report + +If you want to submit a bug report against debhelper, please see +[https://www.debian.org/Bugs/Reporting]() for how to report the bug in the +Debian bug tracker (please file it against the `debhelper` package). + +Users of Debian can use `reportbug debhelper` if they have the +reportbug tool installed. + +You can find the list of open bugs against debhelper at: +[https://bugs.debian.org/src:debhelper](). + + +## Code of Conduct, Social rules and conflict resolution + +The debhelper suite is a part of Debian. Accordingly, the Code of +Conduct, Social rules and conflict resolution from Debian applies to +debhelper and all of its contributors. + +As a guiding principle, we strive to have an open welcoming community +working on making Debian packaging easier. Hopefully, this will be +sufficient for most contributors. For more details, please consider +reading (some) of the documents below. + + + * [Debian's Code of Conduct](https://www.debian.org/code_of_conduct) + + * If you feel a contributor is violating the code of contact, please + contact the [Debian anti-harassment team](https://wiki.debian.org/AntiHarassment) + if you are uncomfortable with engaging with them directly. + + * [Debian's Diversity Statement](https://www.debian.org/intro/diversity) + + * Note that `interact constructively with our community` has the + implication that contributors extend the same acceptance and + welcome to others as they can expect from others based on the + diversity statement. + + * The rationale for this implication is based on the + [Paradoc of tolerance](https://en.wikipedia.org/wiki/Paradox_of_tolerance). + + + * [Debian's Social Contract and Free Software Guidelines](https://www.debian.org/social_contract). + + * (very optional read) [Debian's Constitution](https://www.debian.org/devel/constitution). + + * The primary point of importance from this document is the + debhelper project is subject the Debian's technical committee and + the Debian General Resolution (GR) process. These + bodies/processes can make decisions that the debhelper project + must follow. Notably, the GR process is used for updating the + Debian documents above. |